Difference between revisions of "Development/Tutorials/Plasma5/ThemeDetails"

Jump to: navigation, search
m (Theme Location, Structure and Definition: Mention "translucent" in folders list)
m (Note BlurBehindEffec control is only there since KF 5.57)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<tt>libplasma</tt> provides the Theme class so Plasma elements and other applications, such as KRunner, that need to graphically hint or theme interface elements. This is not a replacement for {{qt|qstyle}}, but rather provides standard elements for things such as box backgrounds.
+
<tt>libKF5Plasma</tt> provides the Theme class so Plasma elements and other applications, such as KRunner, that need to graphically hint or theme interface elements. This is not a replacement for QStyle, but rather provides standard elements for things such as box backgrounds.
  
 
This allows for easy re-theming of the desktop while also keeping elements on the desktop more consistent with each other.
 
This allows for easy re-theming of the desktop while also keeping elements on the desktop more consistent with each other.
  
See also [[Development/Tutorials/Plasma/Theme|Creating a Plasma Theme]].
+
See also [[Development/Tutorials/Plasma5/Theme|Creating a Plasma Theme]].
  
 
== Theme Location, Structure and Definition ==
 
== Theme Location, Structure and Definition ==
Themes are stored in {{path|share/apps/plasma/desktoptheme}}. A theme is described by a .desktop file in {{path|share/apps/desktoptheme}}. The contents of which might look like this:
+
Themes are stored in respective subfolders of {{path|share/plasma/desktoptheme}}. A theme is described by a '''metadata.desktop''' file in the top-level directory of such a subfolder.
 +
 
 +
Beneath this directory one will find the following file structure:
 +
 
 +
* '''colors''': optional a configuration file defining a color scheme that blends well with the images
 +
* '''dialogs/''': images for dialogs
 +
* '''widgets/''': images for widgets
 +
* '''opaque/''': optional directory containing images appropriate for non-compositing environments
 +
* '''translucent/''': optional directory containing images appropriate for when background contrast and blur effect is supported
 +
* '''wallpapers/''': wallpaper image packages
 +
 
 +
== Theme Metadata ==
 +
 
 +
The contents of the '''metadata.desktop''' file might look like this:
  
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
 
[Desktop Entry]
 
[Desktop Entry]
Name=Breeze
+
Name=Electrostorm
Comment=Theme done in the Breeze style
+
Comment=Brings a very dynamic electrical energy atmosphere to the desktop
  
X-KDE-PluginInfo-Author=The KDE Visual Design Group
+
X-KDE-PluginInfo-Author=A Plasma Theme Designer
X-KDE-PluginInfo-Email=kde-artists@kde.org
+
X-KDE-PluginInfo-Email=my@mail.address
X-KDE-PluginInfo-Name=default
+
X-KDE-PluginInfo-Name=electrostorm
X-KDE-PluginInfo-Version=pre0.1
+
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=http://plasma.kde.org
+
X-KDE-PluginInfo-Website=
X-KDE-PluginInfo-Category=
 
X-KDE-PluginInfo-Depends=
 
 
X-KDE-PluginInfo-License=GPL
 
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
 
 
X-Plasma-API=5.0
 
X-Plasma-API=5.0
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The X-KDE-PluginInfo-Name entry must contain the name of the subdirectory in {{path|share/apps/desktoptheme}} where the SVG files for this theme exist.
+
The '''X-KDE-PluginInfo-Name''' entry should match the name of the sub-folder in {{path|share/plasma/desktoptheme}} where the SVG files for this theme exist.
 +
 
 +
If the theme should inherit from another theme than the "default" one, this can be defined by a section like this (where the folder name resp. the X-KDE-PluginInfo-Name would be passed as value):
 +
<syntaxhighlight lang="text">
 +
[Settings]
 +
FallbackTheme=oxygen
 +
</syntaxhighlight>
  
If you do changes to SVG files in your theme, make sure to '''update the version number''' so Plasma can properly refresh its cache.
+
If you do changes to SVG files in your theme, make sure to '''update the version number X-KDE-PluginInfo-Version''' so Plasma can properly refresh its cache.
  
Beneath this directory one will find the following file structure:
+
If your theme is not fully opaque, to improve readability of text or other elements, there are two options to ask the window manager to apply some effect for (KWin supports those):
  
* '''colors''': optional a configuration file defining a colorscheme that blends well with the images
+
a) One is adding some contrast to what is behind windows, panels or toolt ips (disabled by default), which is done by a section like this:
* '''dialogs/''': images for dialogs
+
<syntaxhighlight lang="text">
* '''wallpapers/''': wallpaper packages
+
[ContrastEffect]
* '''widgets/''': images for widgets
+
enabled=true
* '''opaque/''': optional directory containing images appropriate for non-compositing environments
+
contrast=0.3
* '''translucent/''': optional directory containing images appropriate for when background contrast and blur effect is supported
+
intensity=1.9
 +
saturation=1.9
 +
</syntaxhighlight>
 +
b) The other option is blurring what is behind windows, panels or tool tips. This is enabled by default. Since Plasma Frameworks 5.57, this can be disabled by a section like this (ignored otherwise):
 +
<syntaxhighlight lang="text">
 +
[BlurBehindEffect]
 +
enabled=false
 +
</syntaxhighlight>
  
 
== Image Access ==
 
== Image Access ==
 
Theme elements are accessed by path. Whether this maps to literal paths on disk or not is not guaranteed and considered an implementation detail of Plasma::Theme.
 
Theme elements are accessed by path. Whether this maps to literal paths on disk or not is not guaranteed and considered an implementation detail of Plasma::Theme.
  
Therefore, to access the dialog background, one might create an svg in this manner:
+
Therefore, to access the dialog background, one might create an SVG in this manner:
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
Line 57: Line 80:
 
== Wallpaper Access ==
 
== Wallpaper Access ==
  
Themes may optionally provide wallpapers to be used with the theme. These wallpapers must appear in the {{path|wallpapers/}} directory within the theme.
+
Themes may optionally provide wallpaper image packages to be used with the theme. These wallpaper image packages must appear in the {{path|wallpapers/}} directory within the theme.
  
A theme may also define a default wallpaper, wallpaper size and wallpaper file extension to be used in conjunction with the theme. The default wallpaper may either be installed in the standard location for wallpapers or may be shipped with the theme itself. The default wallpaper settings should appear in the theme's metadata.desktop file and contain the following entries:
+
A theme may also define a default wallpaper image, image size and image file extension to be used in conjunction with the theme. It will then be automatically used as wallpaper image, if the current wallpaper type supports the settings (like the "Image") and the user has not yet chosen a custom image.
 +
The default wallpaper image may either be installed in the standard location for wallpaper image packages or may be shipped with the theme itself. The default wallpaper image settings should appear in the theme's '''metadata.desktop''' file and contain the following entries:
  
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
Line 74: Line 98:
 
== Colors ==
 
== Colors ==
  
The colors file follows the standard KDE colorscheme file format and allows a theme to define what colors work best with its theme elements. The colors in this file can be edited with the default color scheme module.  
+
The colors file follows the standard Plasma colorscheme file format and allows a theme to define what colors work best with its theme elements. The colors in this file can be edited with the default color scheme module.  
 
*Make a new colorscheme using the editor in SystemSettings>>Appearance>>Colors.
 
*Make a new colorscheme using the editor in SystemSettings>>Appearance>>Colors.
 
*Save it with a unique name.
 
*Save it with a unique name.
*Open the colorscheme in kate.
+
*Open the colorscheme in a text editor, like Kate.
**Saved at /home/[user]/.kde/share/apps/color-schemes/[unique name].colors
+
**Saved at /home/[user]/.local/share/color-schemes/[unique name].colors
*Copy everything to your plasma colors file except the "[ColorEffects:Disabled]" and "[ColorEffects:Inactive]" sections.
+
*Copy everything to your Plasma theme colors file except the "[ColorEffects:Disabled]" and "[ColorEffects:Inactive]" sections.
 
   
 
   
  
Line 88: Line 112:
 
* '''[Colors:Window]'''
 
* '''[Colors:Window]'''
 
** '''ForegroundNormal''' the text color applied to text on the standard background elements; maps to Theme::TextColor
 
** '''ForegroundNormal''' the text color applied to text on the standard background elements; maps to Theme::TextColor
** '''DecorationHover''' the color used for text highlighting; maps to Theme::HighlightCoor
+
** '''DecorationHover''' the color used for text highlighting; maps to Theme::HighlightColor
 
** '''BackgroundNormal''' the default background color, for items that paint a background themselves, allowing them to blend in with the theme; maps to Theme::BackgroundColor
 
** '''BackgroundNormal''' the default background color, for items that paint a background themselves, allowing them to blend in with the theme; maps to Theme::BackgroundColor
 
* '''[Colors:Button]'''
 
* '''[Colors:Button]'''
Line 113: Line 137:
  
 
== Backgrounds format==
 
== Backgrounds format==
All background svg's (except for desktop wallpapers) must have the following named elements, all of which will be painted at the ''native'' size (and can therefore be bitmaps), except for the center which will be scaled:
+
All background SVG's (except for wallpaper images) must have the following named elements, all of which will be painted at the ''native'' size (and can therefore be bitmaps), except for the center which will be scaled:
 
* '''topleft''': the top left corner
 
* '''topleft''': the top left corner
 
* '''topright''': the top right corner
 
* '''topright''': the top right corner
Line 124: Line 148:
 
* '''center''': the center fill; will be scaled so should be an actual SVG element
 
* '''center''': the center fill; will be scaled so should be an actual SVG element
  
Some plasma components may use the above named elements with prefixes.  For example the panel placed on the left side of the screen uses the "west" prefix ('''west-topleft''', '''west-topright''', etc.).
+
Some Plasma components may use the above named elements with prefixes.  For example the panel placed on the left side of the screen uses the "west" prefix ('''west-topleft''', '''west-topright''', etc.).
  
 
Additionally, the following elements can be used to control the rendering of the backgrounds:
 
Additionally, the following elements can be used to control the rendering of the backgrounds:
Line 131: Line 155:
 
* '''hint-tile-center''': if it exists, the center will not be scaled but rather will be tiled to fit. (Optional, from 4.1 and later)
 
* '''hint-tile-center''': if it exists, the center will not be scaled but rather will be tiled to fit. (Optional, from 4.1 and later)
 
* '''hint-no-border-padding''':  If this element exists, padding will not be added for the borders, and content will therefore be able to use the entire area (inclusive borders).
 
* '''hint-no-border-padding''':  If this element exists, padding will not be added for the borders, and content will therefore be able to use the entire area (inclusive borders).
* '''hint-apply-color-scheme''':  If this element exists, the svg will be colorized using the color scheme colors.  Colorization is applied at 100%, and tapers off on either side, of an HSV color value/intensity of 127. (Optional, From KDE 4.1 and later)
+
* '''hint-apply-color-scheme''':  If this element exists, the SVG will be colorized using the color scheme colors.  Colorization is applied at 100%, and tapers off on either side, of an HSV color value/intensity of 127.
* '''current-color-scheme''': If a style element with this id exists it is replaced by a css-style with colors of the current colorscheme. See below for details. (Optional, From KDE 4.6 and later)
+
* '''current-color-scheme''': If a style element with this id exists it is replaced by a css-style with colors of the current colorscheme. See below for details.
* '''[prefix]-hint-[direction]-margin''': Use this optional hints if you want different margins than the borders size. The [prefix]- part is optional and identifies the prefix of the panel you want to specify the margins. [direction] can be either top, bottom, left or right and indicates the border you want to configure. For top and bottom margins the height of these hints are used, for left and right margins the width. (Optional, From KDE 4.2 and later)
+
* '''[prefix]-hint-[direction]-margin''': Use this optional hints if you want different margins than the borders size. The [prefix]- part is optional and identifies the prefix of the panel you want to specify the margins. [direction] can be either top, bottom, left or right and indicates the border you want to configure. For top and bottom margins the height of these hints are used, for left and right margins the width.
* '''[prefix]-hint-compose-over-border''': if this element is resent, the center element will be drawn with the same size as the total image, composed under the borders and shaped with the alpha mask frame, that has to be present in order to make work this hint(Optional, from KDE 4.5)
+
* '''[prefix]-hint-compose-over-border''': if this element is resent, the center element will be drawn with the same size as the total image, composed under the borders and shaped with the alpha mask frame, that has to be present in order to make work this hint(Optional).
  
From KDE 4.3 can exists an element called overlay (or prefix-overlay if to be appled to a frame with a different prefix) it will be rendered over the frame as a filigrane effects, with the rules given from the following mutually exclusive hints:
+
Next there can be optionally another element called '''overlay''' (or '''[prefix]-overlay''' if to be appled to a frame with a different prefix) it will be rendered over the frame as a filigrane effects, with the rules given from the following mutually exclusive hints:
 
* '''hint-overlay-random-pos''' it will be put at a random position, this works just for applet backgrounds
 
* '''hint-overlay-random-pos''' it will be put at a random position, this works just for applet backgrounds
 
* '''hint-overlay-tile''' tile the overlay
 
* '''hint-overlay-tile''' tile the overlay
 
* '''hint-overlay-stretch''' the overlay will be stretched
 
* '''hint-overlay-stretch''' the overlay will be stretched
* '''hint-overlay-pos-right''' align the overlay at right of the background rather than to the left (from KDE 4.4)
+
* '''hint-overlay-pos-right''' align the overlay at right of the background rather than to the left
* '''hint-overlay-pos-bottom''' align the overlay at bottom of the background rather than to the top (from KDE 4.4)
+
* '''hint-overlay-pos-bottom''' align the overlay at bottom of the background rather than to the top
  
 
===Inkscape extension===
 
===Inkscape extension===
An Inkscape extension exists to automatically rename svg elements with the above naming spec.
+
An Inkscape extension exists to automatically rename SVG elements with the above naming spec.
 
* download the two files at https://websvn.kde.org/trunk/playground/artwork/Oxygen/notmart/inkscapeextensions/
 
* download the two files at https://websvn.kde.org/trunk/playground/artwork/Oxygen/notmart/inkscapeextensions/
 
* copy them to $HOME/.config/inkscape/extensions
 
* copy them to $HOME/.config/inkscape/extensions
Line 152: Line 176:
  
 
=== Using system colors ===
 
=== Using system colors ===
It is possible to apply colors from the color scheme to a graphic. A very easy way to reach this is by adding an element with the id '''hint-apply-color-scheme''' to the svg. In this case the rendered graphic gets converted to monochrome and colorized by the window background color.
+
It is possible to apply colors from the color scheme to a graphic. A very easy way to reach this is by adding an element with the id '''hint-apply-color-scheme''' to the SVG, In this case the rendered graphic gets converted to monochrome and colorized by the window background color.
  
 
[[File:EditingSvgIcon.png]]
 
[[File:EditingSvgIcon.png]]
  
A more flexible solution is available since KDE 4.6 by using css-styling. For this to work the svg must have a style-element with the id '''current-color-scheme'''. Before the graphic is rendered this element gets replaced by a style containing classes where the color attribute is set to the corresponding system color. Currently the following classes are defined:
+
A more flexible solution is available by using CSS-styling. For this to work the SVG must have a style-element with the id '''current-color-scheme'''. Before the graphic is rendered this element gets replaced by a style containing classes where the color attribute is set to the corresponding system color. Currently the following classes are defined:
 
* ColorScheme-Text
 
* ColorScheme-Text
 
* ColorScheme-Background
 
* ColorScheme-Background
Line 169: Line 193:
 
* ColorScheme-ButtonFocus
 
* ColorScheme-ButtonFocus
  
In order to apply a color from a class to an element, its fill or stroke attribute must be '''currentColor''' and of course the name of the wanted class has to be in the class-attribute. Special attention is needed on gradients, as neither the gradient-tags themself nor the stop-tags accept classes. To still get the wanted result one can put a g-tag around them and apply the class to this.
+
In order to apply a color from a class to an element, its fill or stroke attribute must be '''currentColor''' and of course the name of the wanted class has to be in the class-attribute. Special attention is needed on gradients, as neither the gradient-tags themselves nor the stop-tags accept classes. To still get the wanted result one can put a g-tag around them and apply the class to this.
  
 
In the Plasma-framework source repository, two useful tools are present:
 
In the Plasma-framework source repository, two useful tools are present:
 
* ''currentColorFix.sh'': fixes an error in the file format that inkscape often does that would break the coorect application of the stylesheet
 
* ''currentColorFix.sh'': fixes an error in the file format that inkscape often does that would break the coorect application of the stylesheet
* ''apply-stylesheet.sh'': looks in the svg file for certain colors (by default from the Breeze palette) and replaces them with the corresponfing stylesheet class, automating a potential long and tedious job
+
* ''apply-stylesheet.sh'': looks in the SVG file for certain colors (by default from the Breeze palette) and replaces them with the corresponfing stylesheet class, automating a potential long and tedious job
  
 
== Current Theme Elements ==
 
== Current Theme Elements ==
  
Themes get installed to {{path|share/apps/desktoptheme}}. Each theme is stored in a subdirectory with the following file structure
+
Themes get installed to {{path|share/plasma/desktoptheme}}. Each theme is stored in an own sub-folder by the name of the theme with the following file structure (all files can be in either .svg or .svgz format):
  
 
*'''/dialogs''': elements for dialogs
 
*'''/dialogs''': elements for dialogs
**'''/background.svg''': generic dialog background used by the sceensaver password dialog, etc. See the section on backgrounds above for information on the required elements in this file.
+
**'''/background.svg''': generic dialog background used by the screensaver password dialog, etc. See the section on backgrounds above for information on the required elements in this file.
*** '''hint-left-shadow''': from KDE 4.10: optional hints that say how big the shadow is
+
*** '''hint-left-shadow''': optional hints that say how big the shadow is
 
*** '''hint-top-shadow'''
 
*** '''hint-top-shadow'''
 
*** '''hint-right-shadow'''
 
*** '''hint-right-shadow'''
 
*** '''hint-bottom-shadow'''
 
*** '''hint-bottom-shadow'''
 
*'''/widgets''': generic desktop widget background
 
*'''/widgets''': generic desktop widget background
** '''/action-overlays.svgz''': overlays for icons to indicate actions (since KDE 4.4)
+
** '''/action-overlays.svg''': overlays for icons to indicate actions
 
*** ''add-normal'': icon used to add the parent icon to a selection of elements (used for instance in folderview), normal state, there are also ''add-hover'' and ''add-pressed''
 
*** ''add-normal'': icon used to add the parent icon to a selection of elements (used for instance in folderview), normal state, there are also ''add-hover'' and ''add-pressed''
 
*** ''remove-normal'': icon used to remove the parent icon to a selection of elements, normal state, there are also ''remove-hover'' and ''remove-pressed''
 
*** ''remove-normal'': icon used to remove the parent icon to a selection of elements, normal state, there are also ''remove-hover'' and ''remove-pressed''
Line 197: Line 221:
 
***''label0'': the rect for the first label
 
***''label0'': the rect for the first label
 
***''label1'': the rect for the second label
 
***''label1'': the rect for the second label
**'''/arrows.svg''': arrows that match the theme. Four elements should exist in this svg: up-arrow, down-arrow, left-arrow, right-arrow.
+
**'''/arrows.svg''': arrows that match the theme. Four elements should exist in this SVG: up-arrow, down-arrow, left-arrow, right-arrow.
 
**'''/background.svg''': a background image for plasmoids. See the section on backgrounds above for information on the required elements in this file.
 
**'''/background.svg''': a background image for plasmoids. See the section on backgrounds above for information on the required elements in this file.
*** '''hint-left-shadow''': from KDE 4.10: optional hints that say how big the shadow is
+
*** '''hint-left-shadow''': optional hints that say how big the shadow is
 
*** '''hint-top-shadow'''
 
*** '''hint-top-shadow'''
 
*** '''hint-right-shadow'''
 
*** '''hint-right-shadow'''
Line 207: Line 231:
 
***''foreground'': overlay in the foreground of the progressbar
 
***''foreground'': overlay in the foreground of the progressbar
 
***''bar'': the progressbar itself
 
***''bar'': the progressbar itself
***''background'': a 9 pieces svg with the ''background'' prefix, it replaces the background element if available (KDE 4.2 and later)
+
***''background'': a 9 pieces SVG with the ''background'' prefix, it replaces the background element if available
***''hint-stretched-bar'': make the progressbar background element stretched rather than tiled (KDE 4.2 and later)
+
<!--***''hint-stretched-bar'': make the progressbar background element stretched rather than tiled-->
***''bar-active'' and ''bar-inactive'': 9 pieces svgs with the ''bar-active'' and ''bar-inactive'' prefixes, they replace the bar element when available, they will be drawn tiled (KDE4.2 and later)
+
***''bar-active'' and ''bar-inactive'': 9 pieces SVGs with the ''bar-active'' and ''bar-inactive'' prefixes, they replace the bar element when available, they will be drawn tiled
 
***''label0'', ''label1'' and ''label2'': rects for 3 labels to be placed around
 
***''label0'', ''label1'' and ''label2'': rects for 3 labels to be placed around
 +
***''hint-bar-size'': default height of the bar, if not present the default is taken from sum of heights of ''bar-inactive-top'' & ''bar-inactive-bottom''
 
** '''/bar_meter_vertical.svg''': a vertical meter like a vertical progressbar. It has the same format of ''/bar_meter_horizontal.svg''
 
** '''/bar_meter_vertical.svg''': a vertical meter like a vertical progressbar. It has the same format of ''/bar_meter_horizontal.svg''
** '''/branding.svgz''': a little KDE logo that can be customized by distributors as a branding element. Contains a single element called ''brilliant''
+
** '''/branding.svg''': a little Plasma logo that can be customized by distributors as a branding element. Contains a single element called ''brilliant''
** '''/busywidget.svgz''': Used to indicate a busy state, it's a circular image that will be animated with a rotation.
+
** '''/busywidget.svg''': Used to indicate a busy state, it's a circular image that will be animated with a rotation.
 
*** ''busywidget'': the main spinner
 
*** ''busywidget'': the main spinner
 
*** ''paused'': the paused state
 
*** ''paused'': the paused state
** '''/button.svg''': graphics elements for a button widget (KDE 4.2 and later), it needs the followin prefixes:
+
** '''/button.svg''': graphics elements for a button widget, it needs the following prefixes:
 
*** ''normal'' normal button
 
*** ''normal'' normal button
 
*** ''pressed'' pressed button  
 
*** ''pressed'' pressed button  
 
*** ''active'' button under mouse. Active can have ticker borders that would be rendered outside the widget. It's useful to do a glowing effect DEPRECATED: use ''hover'' instead
 
*** ''active'' button under mouse. Active can have ticker borders that would be rendered outside the widget. It's useful to do a glowing effect DEPRECATED: use ''hover'' instead
*** ''hover'' element that will be in the background of the widget, will act as a border (useful for glow effects) since KDE 4.5
+
*** ''hover'' element that will be in the background of the widget, will act as a border (useful for glow effects)
*** ''shadow'' a shadow for the button, can be bigger than the button itself since KDE 4.5
+
*** ''shadow'' a shadow for the button, can be bigger than the button itself
 
*** ''focus'' keyboard focus rectangle superimposed to the button graphics
 
*** ''focus'' keyboard focus rectangle superimposed to the button graphics
** '''/calendar.svg''': graphics for a calendar widget, since 4.3
+
** '''/calendar.svg''': graphics for a calendar widget
 
*** ''weeksColumn'': background for the vertical column with week numbers in it.
 
*** ''weeksColumn'': background for the vertical column with week numbers in it.
 
*** ''weekDayHeader'': background for the row with week day names in it.
 
*** ''weekDayHeader'': background for the row with week day names in it.
Line 235: Line 260:
 
**'''/clock.svg''': an analog clock face. it must have the following named elements:
 
**'''/clock.svg''': an analog clock face. it must have the following named elements:
 
*** ''ClockFace'': the background of the clock, usually containing the numbers, etc
 
*** ''ClockFace'': the background of the clock, usually containing the numbers, etc
*** ''HourHand'': the hour hand, pointing down in the svg
+
*** ''HourHand'': the hour hand, pointing down in the SVG
*** ''MinuteHand'': the minute hand, pointing down in the svg
+
*** ''MinuteHand'': the minute hand, pointing down in the SVG
*** ''SecondHand'': the second hand, pointing down in the svg
+
*** ''SecondHand'': the second hand, pointing down in the SVG
*** ''HourHandShadow'', ''MinuteHandShadow'' and ''SecondHandShadow'': drop shadows for the hands (optional, KDE 4.1 and later)  
+
*** ''HourHandShadow'', ''MinuteHandShadow'' and ''SecondHandShadow'': drop shadows for the hands (optional)
 
*** ''HandCenterScrew'': the "pin" that holds the hands together in the center
 
*** ''HandCenterScrew'': the "pin" that holds the hands together in the center
 
*** ''Glass'': a final overlay which allows for things such as the appearance of glass
 
*** ''Glass'': a final overlay which allows for things such as the appearance of glass
 
*** ''hint-square-clock'': if present the shape of the clock will be square rather than round
 
*** ''hint-square-clock'': if present the shape of the clock will be square rather than round
*** Note: In the svg, the Hand elements must be placed in a position that indicates the time 6:30:30. The y-axis position of the Hand elements with respect to the center of ClockFace is the one they will have in the rendered applet. The x-axis position of the Hand elements does not matter. The Shadow elements should have the same y-axis position as their Hand element counterpart.
+
*** ''hint-[hand(shadow)]-rotation-center-offset'': the point of a hand (shadow) where it is "pinned" to the clock center, defined by the center of the hint, relative to the element position (can be outside the element), with ''[hand(shadow)]'' being ''hourhand'', ''hourhandshadow'', ''minutehand'', ''minutehandshadow'', ''secondhand'', ''secondhandshadow'', default is "(width/2, width/2)" from top-left of the hand (shadow) element  (since Plasma 5.16)
** '''/configuration-icons''': it's a set of simple icons that are meant to be shortcuts for configuration actions (KDE 4.2 and later). Must contain the following elements:
+
*** ''hint-hands-shadow-offset-to-west'' or ''hint-hands-shadows-offset-to-east'': horizontal offset of the hands shadows, default is 0 offset (since Plasma 5.16)
 +
*** ''hint-hands-shadow-offset-to-north'' or ''hint-hands-shadow-offset-to-south'': vertical offset of the hands shadows, default is 0 offset (since Plasma 5.16)
 +
*** Note: In the SVG, the Hand elements as well as their optional Shadow counterparts must be oriented in a direction as the one indicating the time 6:30:30. The relative position of the Hand elements as well as their optional Shadow counterparts with respect to the center of ClockFace does not matter.
 +
** '''/configuration-icons''': it's a set of simple icons that are meant to be shortcuts for configuration actions. Must contain the following elements:
 
*** ''close'': a close icon
 
*** ''close'': a close icon
 
*** ''configure'': a setup action
 
*** ''configure'': a setup action
Line 261: Line 289:
 
*** ''add'' and ''remove'': specular actions, adding and removing for instance an item from a list
 
*** ''add'' and ''remove'': specular actions, adding and removing for instance an item from a list
 
*** ''delete'': the (potentially dangerous) action of deleting something
 
*** ''delete'': the (potentially dangerous) action of deleting something
** '''/containment-controls.svg''': handles for the control used to resize the panel (KDE 4.1 and later).  The following elements are required.
+
** '''/containment-controls.svg''': handles for the control used to resize the panel.  The following elements are required.
 
*** ''maxslider'' maximum size slider, south position
 
*** ''maxslider'' maximum size slider, south position
 
*** ''minslider'' minimum size slider, south position
 
*** ''minslider'' minimum size slider, south position
Line 267: Line 295:
 
*** Each of the above elements must be present with ''north'', ''south'', ''east'' and ''west'' prefixes for each panel position.
 
*** Each of the above elements must be present with ''north'', ''south'', ''east'' and ''west'' prefixes for each panel position.
 
*** There are also four backgrounds (north, south, east and west orientations) for the ruler widget itself in the "Backgrounds format", since the width of the widget is 100% the elements of left and right (or north and bottom if vertical) are not needed
 
*** There are also four backgrounds (north, south, east and west orientations) for the ruler widget itself in the "Backgrounds format", since the width of the widget is 100% the elements of left and right (or north and bottom if vertical) are not needed
** '''/dragger.svgz''': meant to be a generic drag handle (not currently used but available). It needs to contain the same elements as other backgrounds, see the section about backgrounds above. In addition it needs the following element:
+
** '''/dragger.svg''': meant to be a generic drag handle (not currently used but available). It needs to contain the same elements as other backgrounds, see the section about backgrounds above. In addition it needs the following element:
 
*** ''hint-preferred-icon-size'': the size icons within the drag handle should get. The vertical size of the dragger is also derived from this: this size hint + the dragger's margins.
 
*** ''hint-preferred-icon-size'': the size icons within the drag handle should get. The vertical size of the dragger is also derived from this: this size hint + the dragger's margins.
** '''/frame.svgz''' : a generic frame, used mostly for widget containers, to visually group widgets together. It must contain the following prefixes, for different 3d looks:
+
** '''/frame.svg''' : a generic frame, used mostly for widget containers, to visually group widgets together. It must contain the following prefixes, for different 3d looks:
 
*** ''sunken''
 
*** ''sunken''
 
*** ''plain''
 
*** ''plain''
 
*** ''raised''
 
*** ''raised''
** '''/glowbar.svgz''' : a frame without a prefix, it represents a glow, it's used for instance in Plasma Desktop for the panel autohide unhide hint.
+
** '''/glowbar.svg''' : a frame without a prefix, it represents a glow, it's used for instance in Plasma Desktop for the panel autohide unhide hint.
** '''/line.svgz''' : a simple line use to separate items in layouts, containe ''vertical-line'' and ''horizzontal-line'' elements (since KDE 4.3)
+
** '''/line.svg''' : a simple line use to separate items in layouts, containe ''vertical-line'' and ''horizzontal-line'' elements
** '''/lineedit.svgz''': it's a framesvg, used to style line edits, spinboxes and other similar fields (since KDE 4.4) it must have the following prefixes
+
** '''/lineedit.svg''': it's a framesvg, used to style line edits, spinboxes and other similar fields, it must have the following prefixes
 
*** ''base'': the background of the line edit
 
*** ''base'': the background of the line edit
 
*** ''focus'': will be drawn outside base, when the line edit has input focus
 
*** ''focus'': will be drawn outside base, when the line edit has input focus
 
*** ''hover'': will be drawn outside base, when the line edit is under the mouse
 
*** ''hover'': will be drawn outside base, when the line edit is under the mouse
** '''/listitem.svgz''': used for "opened"/clicked notifications (since KDE 4.10) 
+
** '''/listitem.svg''': used for "opened"/clicked notifications
** '''/monitor.svgz''' : represents a screen, it's used in places such as the wallpaper config dialog. It contains a frame without prefixes and the following extra elements:
+
** '''/monitor.svg''' : represents a screen, it's used in places such as the wallpaper config dialog. It contains a frame without prefixes and the following extra elements:
 
*** ''glass'' : glass reflection effect over the screen
 
*** ''glass'' : glass reflection effect over the screen
 
*** ''base'' : a stand for the monitor
 
*** ''base'' : a stand for the monitor
** '''/pager.svgz''' : graphic elements for the little screens of the pager, it must have 3 frames with the following prefixes:
+
** '''/notes.svg''' : design of note stickers, with 10 different color variants:
 +
*** ''[color]-notes'' : colored note sticker with [color] one of: "white", "black", "red", "orange", "yellow", "green", "blue", "pink", "translucent", "translucent-light"
 +
** '''/pager.svg''' : graphic elements for the little screens of the pager, it must have 3 frames with the following prefixes:
 
*** ''normal'' : all virtual desktops
 
*** ''normal'' : all virtual desktops
 
*** ''active'' : active virtual desktop
 
*** ''active'' : active virtual desktop
 
*** ''hover'' : virtual desktop under mouse
 
*** ''hover'' : virtual desktop under mouse
 
**'''/panel-background.svg''': the background image for panels.
 
**'''/panel-background.svg''': the background image for panels.
*** If you want to create different background for panels located at the top, bottom, left or right, then also create sets of background elements with the following prefixes: ''north'', ''south'', ''west'' and ''east'' respectively. For example the center element of the left positioned panel's background should be named ''west-center''. (KDE 4.1 and later)
+
*** If you want to create different background for panels located at the top, bottom, left or right, then also create sets of background elements with the following prefixes: ''north'', ''south'', ''west'' and ''east'' respectively. For example the center element of the left positioned panel's background should be named ''west-center''.
*** When the panel is not 100% wide/tall the north, south etc. prefixes becomes ''north-mini'', ''south-mini'' etc. (KDE 4.2 and later). Please note that if KRunner <menuchoice>Positioning</menuchoice> is set to <menuchoice>Top edge of screen</menuchoice> (which is default), then KDE treats it as not 100% wide north panel.
+
<!--*** When the panel is not 100% wide/tall the north, south etc. prefixes becomes ''north-mini'', ''south-mini'' etc. . Please note that if KRunner <menuchoice>Positioning</menuchoice> is set to <menuchoice>Top edge of screen</menuchoice> (which is default), then Plasma treats it as not 100% wide north panel.-->
 
*** All prefixes fallback to a no prefix version when not available
 
*** All prefixes fallback to a no prefix version when not available
 
*** if a prefix called ''shadow'' is available, it will be used as a drop shadow for the panel when compositing is available.
 
*** if a prefix called ''shadow'' is available, it will be used as a drop shadow for the panel when compositing is available.
 
** '''/plot-background.svg''': a background for plotter (graph) widgets, such as the plots in ksysguard
 
** '''/plot-background.svg''': a background for plotter (graph) widgets, such as the plots in ksysguard
** '''/scrollbar.svgz''' : the classical ''elevator'' scrollbar, must have the following elemens : ''arrow-up'', ''mouseover-arrow-up'', ''sunken-arrow-up'', same 3 elements for ''arrow-left'', ''arrow-right'' and ''arrow-bottom''. From KDE 4.10 it can have an element called ''hint-scrollbar-size'' that says at what size the scrollbar should be rendered (width if vertical, height if horizontal). It must also have frames with the following prefixes:
+
** '''/scrollbar.svg''' : the classical ''elevator'' scrollbar, must have the following elemens : ''arrow-up'', ''mouseover-arrow-up'', ''sunken-arrow-up'', same 3 elements for ''arrow-left'', ''arrow-right'' and ''arrow-bottom''. It can have an element called ''hint-scrollbar-size'' that says at what size the scrollbar should be rendered (width if vertical, height if horizontal). It must also have frames with the following prefixes:
 
*** ''slider''
 
*** ''slider''
 
*** ''mouseover-slider''
 
*** ''mouseover-slider''
Line 299: Line 329:
 
*** ''background-vertical''
 
*** ''background-vertical''
 
*** ''background-horizontal''
 
*** ''background-horizontal''
** '''/scrollwidget''': used by Plasma::ScrollWidget, it has a single prefix (KDE4.4 and later)
+
** '''/scrollwidget''': used by Plasma::ScrollWidget, it has a single prefix
 
*** ''border'': a border used when the scrollbar is enabled
 
*** ''border'': a border used when the scrollbar is enabled
** '''/slider.svgz''': used to theme sliders (since KDE 4.3) it must have the following elements:
+
** '''/slider.svg''': used to theme sliders, it must have the following elements:
 
*** ''vertical-slider-line'': the background for vertical sliders, it indicates how much the indicator can scroll
 
*** ''vertical-slider-line'': the background for vertical sliders, it indicates how much the indicator can scroll
 
*** ''vertical-slider-handle'': the handle for vertical sliders
 
*** ''vertical-slider-handle'': the handle for vertical sliders
*** ''vertical-slider-focus'': background for the handle when it has input focus (since KDE 4.4)
+
*** ''vertical-slider-focus'': background for the handle when it has input focus
*** ''vertical-slider-hover'': background for the handle when it is under the mouse (since KDE 4.4)
+
*** ''vertical-slider-hover'': background for the handle when it is under the mouse
*** ''groove'': groove for the slider (since KDE 4.8 replaces *-slider-line)
+
*** ''groove'': groove for the slider (since Plasma 4.8 replaces *-slider-line)
*** ''groove-highlight'': highlight part of the groove (since KDE 4.8 replaces *-slider-line)
+
*** ''groove-highlight'': highlight part of the groove (since Plasma 4.8 replaces *-slider-line)
 
*** ''horizontal-slider-line'': the background for horizontal sliders
 
*** ''horizontal-slider-line'': the background for horizontal sliders
 
*** ''horizontal-slider-handle'': the handle for horizontal sliders
 
*** ''horizontal-slider-handle'': the handle for horizontal sliders
*** ''horizontal-slider-focus'': background for the handle when it has input focus (since KDE 4.4)
+
*** ''horizontal-slider-focus'': background for the handle when it has input focus
*** ''horizontal-slider-hover'': background for the handle when it is under the mouse (since KDE 4.4)
+
*** ''horizontal-slider-hover'': background for the handle when it is under the mouse
**'''/tabbar.svgz''': graphics elements for tabbars: contains 4 frames, each one for tabs in the possible orientatios a tabbar can be relative to its contents, with the prefixes:
+
**'''/tabbar.svg''': graphics elements for tabbars: contains 4 frames, each one for tabs in the possible orientations a tabbar can be relative to its contents, with the prefixes:
 
*** ''north''
 
*** ''north''
 
*** ''west''
 
*** ''west''
 
*** ''south''
 
*** ''south''
 
*** ''east''
 
*** ''east''
**'''/tasks.svg''': task item backgrounds for tasks (KDE 4.1 and later). See the section on backgrounds above for information on the required elements in this file.  The following element prefixes are required:
+
**'''/tasks.svg''': task item backgrounds for tasks. See the section on backgrounds above for information on the required elements in this file.  The following element prefixes are required:
 
*** ''focus'': background of focused task item
 
*** ''focus'': background of focused task item
*** ''hover'': background when the pointer hovers the task item. From KDE 4.2 focus and hover can have ticker borders that will be painted outside the task button, useful to make a glow effect.
+
*** ''hover'': background when the pointer hovers the task item. Focus and hover can have ticker borders that will be painted outside the task button, useful to make a glow effect.
 
*** ''attention'': background when tasks item is trying to get attention
 
*** ''attention'': background when tasks item is trying to get attention
 
*** ''normal'': background of normal, unfocused task item
 
*** ''normal'': background of normal, unfocused task item
Line 328: Line 358:
 
** '''/tooltip.svg''': background for tooltips used for instance in the taskbar and with icons. See the section on backgrounds above for information on the required elements in this file.
 
** '''/tooltip.svg''': background for tooltips used for instance in the taskbar and with icons. See the section on backgrounds above for information on the required elements in this file.
 
** '''/translucentbackground.svg''': a standard background image for plasmoids that for their nature are bigger and with not much text. In this case a translucent background looks better. It needs the same elements of background.svg in it. If this file is not present, the plasmoids that uses this will use background.svg instead.
 
** '''/translucentbackground.svg''': a standard background image for plasmoids that for their nature are bigger and with not much text. In this case a translucent background looks better. It needs the same elements of background.svg in it. If this file is not present, the plasmoids that uses this will use background.svg instead.
** '''/media-delegate.svgz''': intended to be used as delegate for media types: as KDE 4.7 contains a single prefix: picture.
+
** '''/media-delegate.svg''': intended to be used as delegate for media types: it contains a single prefix: picture.
** '''/viewitem.svgz''': controls the background look of selections (results in KRunner, networks in network applet), it can have 4 elements of 9 parts each with prefix ''normal'', ''hover'', ''selected'', ''selected+hover''.
+
** '''/viewitem.svg''': controls the background look of selections (results in KRunner, networks in network applet), it can have 4 elements of 9 parts each with prefix ''normal'', ''hover'', ''selected'', ''selected+hover''.
** '''/toolbar.svgz''': used in the ToolBar QML component, can be used in custom applications in a similar way, contains a single frame without prefix. Since KDE 4.8.
+
** '''/toolbar.svg''': used in the ToolBar QML component, can be used in custom applications in a similar way, contains a single frame without prefix.
  
 
=="Opaque" folder==
 
=="Opaque" folder==
  
In the folder {{path|share/apps/desktoptheme/opaque}} the same hierarchy can be found: when compositing is disabled files in this folder are preferred over the corresponding ones listed above. Only background for top level windows are appropriate to go in this folder.
+
In the special subfolder {{path|opaque/}} the same hierarchy can be found again: when compositing is disabled files in this folder are preferred over the corresponding ones listed above. Only background for top level windows are appropriate to go in this folder.
  
Since top-level windows will be shaped according to the transparency of the svg and window shapes don't support alpha-blending, if the svg has rounded borders they should have a shape that don't require antialiasing, like the following example.
+
Since top-level windows will be shaped according to the transparency of the SVG and window shapes don't support alpha-blending, if the SVG has rounded borders they should have a shape that don't require anti-aliasing, like the following example.
  
 
[[Image:No_composite_plasma_svg.jpg]]
 
[[Image:No_composite_plasma_svg.jpg]]
Line 342: Line 372:
 
=="translucent" folder ==
 
=="translucent" folder ==
  
In the folder {{path|share/apps/desktoptheme/translucent}} the same hierarchy is used: when the KWin ''blurbehind'' effect is enabled the file under this folder will be used if found. As the opaque folder, only elements that will be rendered as window backgrounds should be present in this folder, so the dialogs folder, plus the panel and tooltip backgrounds. When is possible to blur the background of the window, the graphics can be more transparent, keeping the window text readable.
+
In the special folder {{path|translucent/}} the same hierarchy is used as well: when the KWin ''Background Contrast'' effect is enabled the file under this folder will be used if found. As the opaque folder, only elements that will be rendered as window backgrounds should be present in this folder, so the dialogs folder, plus the panel and tooltip backgrounds. When is possible to blur the background of the window, the graphics can be more transparent, keeping the window text readable.
  
 
=="icons" folder==
 
=="icons" folder==
  
In the folder {{path|share/apps/desktoptheme/icons}}, SVG files that contain scalable icons for use with application status items (e.g. icons in the system tray) are contained.
+
In the folder {{path|icons/}}, SVG files that contain scalable icons for use with application status items (e.g. icons in the system tray) are contained.
  
The default theme contains the following SVGs:
+
Some of the common icons:
  
* audio.svgz
+
* audio.svg
* battery.svgz
+
* battery.svg
* device.svgz
+
* computer.svg
* klipper.svgz
+
* configure.svg
* kwalletmanager.svgz
+
* device.svg
* nepomuk.svgz
+
* input.svg
* network.svgz
+
* media.svg
* notification.svgz
+
* network.svg
* preferences.svgz
+
* notification.svg
* wallet.svgz
+
* preferences.svg
 +
* start.svg
 +
* system.svg
  
The files are named the same as the matching icon theme names or their prefix (both work, which is why "audio" matches for mixers, e.g.). Other icons can be added as long as they match the names of requested icons by the application status items.
+
The files are named the same as the icon theme name or their prefix, e.g. "audio.svg" or "audio-volume-high.svg". Multiple icons can be contained within a single file whose name must match the full icon name, e.g. "audio.svg" can contain elements named "audio-volume-muted", "audio-volume-low", "audio-volume-medium", and "audio-volume-high".
  
== Theming Application Icons in the Systemtray ==
+
== Theming Application Icons in the System Tray ==
  
Applications that use a function called setIconByName can have their icon in the system tray themed. Applications can have more than one icon (for example Konversation flashes between two different icons to hilight when your username is mentioned and Kpackagekit changes it's icon depending on the status of it's upgrade / installs). Theming these icons requires firstly that an application has been coded to use setIconByName, and secondly that you call your svg object by the same name (use ctrl+shift+o in Inkscape). Then you can just put your .svgz in {{path|share/apps/desktoptheme/default/icons}} (changing default to your theme folder name).
+
Applications that use a function called setIconByName can have their icon in the system tray themed. Applications can have more than one icon (for example Konversation flashes between two different icons to highlight when your username is mentioned and Kpackagekit changes it's icon depending on the status of it's upgrade / installs). Theming these icons requires firstly that an application has been coded to use setIconByName, and secondly that you call your SVG object by the same name (use Ctrl+Shift-O in Inkscape). Then you can just put your .svg in {{path|share/plasma/desktoptheme/[themename]/icons}}.
  
 
The following is an attempt to list known icon names that may be themed by this method. Please add any other known icon names and the object ID here to help other people making themes:
 
The following is an attempt to list known icon names that may be themed by this method. Please add any other known icon names and the object ID here to help other people making themes:
  
 
* Amarok
 
* Amarok
** filename: '''amarok.svgz'''
+
** filename: '''amarok.svg'''
 
*** ID: '''amarok'''
 
*** ID: '''amarok'''
 
* audio (for kmix, veromix, a.o.)
 
* audio (for kmix, veromix, a.o.)
** filename: '''audio.svgz'''
+
** filename: '''audio.svg'''
 
*** volume muted ID: '''audio-volume-muted'''
 
*** volume muted ID: '''audio-volume-muted'''
 
*** volume low ID: '''audio-volume-low'''
 
*** volume low ID: '''audio-volume-low'''
Line 379: Line 411:
 
*** volume high ID: '''audio-volume-high'''
 
*** volume high ID: '''audio-volume-high'''
 
* battery
 
* battery
** filename: '''battery.svgz'''
+
** filename: '''battery.svg'''
 
*** battery (always shown object) ID: '''Battery'''
 
*** battery (always shown object) ID: '''Battery'''
 
*** on powerline ID: '''AcAdapter'''
 
*** on powerline ID: '''AcAdapter'''
 
*** no battery found ID: '''Unavailable'''
 
*** no battery found ID: '''Unavailable'''
*** battery on 10% ID: '''Fill10''' ''(new in 4.11)''
+
*** battery on 10% ID: '''Fill10'''
 
*** battery on 20% ID: '''Fill20'''
 
*** battery on 20% ID: '''Fill20'''
*** battery on 30% ID: '''Fill30''' ''(new in 4.11)''
+
*** battery on 30% ID: '''Fill30'''
*** battery on 40% ID: '''Fill40'''
+
*** […]
*** battery on 50% ID: '''Fill50''' ''(new in 4.11)''
+
*** battery on 90% ID: '''Fill90'''
*** battery on 60% ID: '''Fill60'''
 
*** battery on 70% ID: '''Fill70''' ''(new in 4.11)''
 
*** battery on 80% ID: '''Fill80'''
 
*** battery on 90% ID: '''Fill90''' ''(new in 4.11)''
 
 
*** battery on 100% ID: '''Fill100'''
 
*** battery on 100% ID: '''Fill100'''
 
* device (the device-notifier)
 
* device (the device-notifier)
** filename: '''device.svgz'''
+
** filename: '''device.svg'''
 
*** ID: '''device-notifier'''
 
*** ID: '''device-notifier'''
 
* juk
 
* juk
** filename: '''juk.svgz'''
+
** filename: '''juk.svg'''
 
*** ID: '''juk'''
 
*** ID: '''juk'''
 
* KGet
 
* KGet
** filename: '''kget.svgz'''
+
** filename: '''kget.svg'''
 
*** ID: '''kget'''
 
*** ID: '''kget'''
 
* Klipper
 
* Klipper
** filename: '''klipper.svgz'''
+
** filename: '''klipper.svg'''
 
*** ID: '''klipper'''
 
*** ID: '''klipper'''
 
* Konversation
 
* Konversation
 
** filename: '''konversation'''
 
** filename: '''konversation'''
 
*** ID: '''konversation'''
 
*** ID: '''konversation'''
** filename: '''konv_message.svgz''' (new incomming message)
+
** filename: '''konv_message.svg''' (new incomming message)
 
*** ID: '''konv_message'''
 
*** ID: '''konv_message'''
 
* Kopete
 
* Kopete
** filename: '''kopete.svgz'''
+
** filename: '''kopete.svg'''
 
*** öffline ID: '''kopete-offline'''
 
*** öffline ID: '''kopete-offline'''
 
*** online ID: '''kopete'''
 
*** online ID: '''kopete'''
 
*** other statuses are not supported atm
 
*** other statuses are not supported atm
 
* Korgac
 
* Korgac
** filename: '''korgac.svgz'''
+
** filename: '''korgac.svg'''
 
*** ID: '''korgac'''
 
*** ID: '''korgac'''
 
* Ktorrent
 
* Ktorrent
** filename: '''ktorrent.svgz'''
+
** filename: '''ktorrent.svg'''
 
*** ID: '''ktorrent'''
 
*** ID: '''ktorrent'''
 
* message-indicator
 
* message-indicator
** filename: '''message-indicator.svgz'''
+
** filename: '''message-indicator.svg'''
 
*** standard ID: '''normal'''
 
*** standard ID: '''normal'''
 
*** new message ID: '''new'''
 
*** new message ID: '''new'''
 
* Nepomuk
 
* Nepomuk
** filename: '''nepomuk.svgz'''
+
** filename: '''nepomuk.svg'''
 
*** ID: '''nepomuk'''
 
*** ID: '''nepomuk'''
 
* Network-management-plasmoid
 
* Network-management-plasmoid
** filename: '''network.svgz'''
+
** filename: '''network.svg'''
 
*** wired online ID: '''network-wired-activated'''
 
*** wired online ID: '''network-wired-activated'''
 
*** wired offline ID: '''network-wired'''
 
*** wired offline ID: '''network-wired'''
Line 449: Line 477:
 
*** mobile broadband with access technology on 0% ID: '''network-mobile-0-technology''' (''technology'' can be: ''none, gprs, edge, umts, hsdpa, hsupa, hspa, lte'')
 
*** mobile broadband with access technology on 0% ID: '''network-mobile-0-technology''' (''technology'' can be: ''none, gprs, edge, umts, hsdpa, hsupa, hspa, lte'')
 
* preferences (some apps like bluedevil, krandrtray, text-to-speech)
 
* preferences (some apps like bluedevil, krandrtray, text-to-speech)
** filename: '''preferences.svgz'''
+
** filename: '''preferences.svg'''
 
*** bluedevil online ID: '''preferences-system-bluetooth'''
 
*** bluedevil online ID: '''preferences-system-bluetooth'''
 
*** bluedevil offline ID: '''preferences-system-bluetooth-inactive'''
 
*** bluedevil offline ID: '''preferences-system-bluetooth-inactive'''
Line 456: Line 484:
 
*** activity manager ID: '''preferences-activities'''
 
*** activity manager ID: '''preferences-activities'''
 
* Printer applet
 
* Printer applet
** filename: '''printer.svgz'''
+
** filename: '''printer.svg'''
 
*** ID: '''printer'''
 
*** ID: '''printer'''
 
* Quassel IRC
 
* Quassel IRC
** filename: '''quassel.svgz'''
+
** filename: '''quassel.svg'''
*** quassel öffline ID: '''quassel_inactive''' ("quassel-inactive" in kde 4.10)
+
*** quassel öffline ID: '''quassel-inactive'''
 
*** quassel online ID: '''quassel'''
 
*** quassel online ID: '''quassel'''
*** quassel new message ID: '''quassel_message''' ("quassel-message" in kde 4.10)
+
*** quassel new message ID: '''quassel-message'''
 
* KWallet
 
* KWallet
** filename: '''wallet.svgz'''
+
** filename: '''wallet.svg'''
 
*** open ID: '''wallet-open'''
 
*** open ID: '''wallet-open'''
 
*** closed ID: '''wallet-closed'''
 
*** closed ID: '''wallet-closed'''
 
At the time of writing, KDE-PIM (Kmail, Akregator etc) do not yet use setIconByName and thus aren't able to be themed this way. Reportedly, this is is coming in Kontact 2.
 

Latest revision as of 19:29, 3 June 2019

libKF5Plasma provides the Theme class so Plasma elements and other applications, such as KRunner, that need to graphically hint or theme interface elements. This is not a replacement for QStyle, but rather provides standard elements for things such as box backgrounds.

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

See also Creating a Plasma Theme.

Theme Location, Structure and Definition

Themes are stored in respective subfolders of share/plasma/desktoptheme. A theme is described by a metadata.desktop file in the top-level directory of such a subfolder.

Beneath this directory one will find the following file structure:

  • colors: optional a configuration file defining a color scheme that blends well with the images
  • dialogs/: images for dialogs
  • widgets/: images for widgets
  • opaque/: optional directory containing images appropriate for non-compositing environments
  • translucent/: optional directory containing images appropriate for when background contrast and blur effect is supported
  • wallpapers/: wallpaper image packages

Theme Metadata

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

[Desktop Entry]
Name=Electrostorm
Comment=Brings a very dynamic electrical energy atmosphere to the desktop

X-KDE-PluginInfo-Author=A Plasma Theme Designer
[email protected]
X-KDE-PluginInfo-Name=electrostorm
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-Website=
X-KDE-PluginInfo-License=GPL
X-Plasma-API=5.0

The X-KDE-PluginInfo-Name entry should match the name of the sub-folder in share/plasma/desktoptheme where the SVG files for this theme exist.

If the theme should inherit from another theme than the "default" one, this can be defined by a section like this (where the folder name resp. the X-KDE-PluginInfo-Name would be passed as value):

[Settings]
FallbackTheme=oxygen

If you do changes to SVG files in your theme, make sure to update the version number X-KDE-PluginInfo-Version so Plasma can properly refresh its cache.

If your theme is not fully opaque, to improve readability of text or other elements, there are two options to ask the window manager to apply some effect for (KWin supports those):

a) One is adding some contrast to what is behind windows, panels or toolt ips (disabled by default), which is done by a section like this:

[ContrastEffect]
enabled=true
contrast=0.3
intensity=1.9
saturation=1.9

b) The other option is blurring what is behind windows, panels or tool tips. This is enabled by default. Since Plasma Frameworks 5.57, this can be disabled by a section like this (ignored otherwise):

[BlurBehindEffect]
enabled=false

Image Access

Theme elements are accessed by path. Whether this maps to literal paths on disk or not is not guaranteed and considered an implementation detail of Plasma::Theme.

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

Plasma::Theme theme;
QSvgRenderer svg(theme.image("dialogs/background"));

It is generally recommended to use Plasma::Svg instead of QSvgRenderer directly, however. This is because Plasma::Svg uses caching where it can. Remember to call resize() on the Plasma::Svg before painting with it!

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

Wallpaper Access

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 extension to be used in conjunction with the theme. It will then be automatically used as wallpaper image, if the current wallpaper type supports the settings (like the "Image") and the user has not yet chosen a custom image. The default wallpaper image may either be installed in the standard location for wallpaper image packages or may be shipped with the theme itself. The default wallpaper image settings should appear in the theme's metadata.desktop 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>

Reaction to Theme Changes

If you use Plasma::Svg, changes to the theme are automatically picked up. Otherwise, you can connect to the changed() signal in the Plasma::Theme class. This signal is emitted whenever the theme is changed, which may be triggered by the user switching the theme used or system changes such as a composite manager becoming available.

Colors

The colors file follows the standard Plasma colorscheme file format and allows a theme to define what colors work best with its theme elements. The colors in this file can be edited with the default color scheme module.

  • Make a new colorscheme using the editor in SystemSettings>>Appearance>>Colors.
  • Save it with a unique name.
  • Open the colorscheme in a text editor, like Kate.
    • Saved at /home/[user]/.local/share/color-schemes/[unique name].colors
  • Copy everything to your Plasma theme 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 list of color entries in the colors file that are currently actively used in a Plasma theme:

  • [Colors:Window]
    • ForegroundNormal the text color applied to text on the standard background elements; maps to Theme::TextColor
    • DecorationHover the color used for text highlighting; maps to Theme::HighlightColor
    • BackgroundNormal the default background color, for items that paint a background themselves, allowing them to blend in with the theme; maps to Theme::BackgroundColor
  • [Colors:Button]
    • ForegroundNormal the text color to use on push buttons; maps to Theme::ButtonTextColor
    • BackgroundNormal used for hinting buttons; maps to Theme::ButtonBackgroundColor
    • ForegroundActive color used to tint BackgroundNormal for final button hinting color
  • [Colors:View]
    • ForegroundLink clickable text link font color
    • ForegroundVisited visited clickable text link font color

Other colors in the file may be used by individual widgets or used in the future, so it doesn't hurt to provide a complete colorscheme file and is probably a safer strategy.

Currently also used by individual widgets, which should give a good idea of additional usage patterns:

  • [Colors:View]
    • ForegroundActive used by the digital and fuzzy clocks for the default text color, dictionary widget for results text, microblog for status update text
    • ForegroundInactive used by the pager to draw non-active windows and frames, microblog for user names
    • ForegroundNormal used by microblog for status update entry area background
  • [Colors:Complementary]

Same roles as Colors:Window, those are used in areas such as the logout screen, the screen locker etc, in order for them to have independent colors compared to normal plasmoids.

Note that some of these may end up folded back into Plasma::Theme properly at some point.

Backgrounds format

All background SVG's (except for wallpaper images) must have the following named elements, all of which will be painted at the native size (and can therefore be bitmaps), except for the center which will be scaled:

  • topleft: the top left corner
  • topright: the top right corner
  • bottomleft: the bottom left corner
  • bottomright: the bottom right corner
  • top: the top bar between the two top corners
  • left: the left bar between the two left corners
  • right: the right bar between the two right corners
  • bottom: the bottom bar between the two bottom corners
  • center: the center fill; will be scaled so should be an actual SVG element

Some Plasma components may use the above named elements with prefixes. For example the panel placed on the left side of the screen uses the "west" prefix (west-topleft, west-topright, etc.).

Additionally, the following elements can be used to control the rendering of the backgrounds:

  • hint-stretch-borders: if it exists, the borders will not be tiled but rather will be stretched to fit
  • hint-tile-center: if it exists, the center will not be scaled but rather will be tiled to fit. (Optional, from 4.1 and later)
  • hint-no-border-padding: If this element exists, padding will not be added for the borders, and content will therefore be able to use the entire area (inclusive borders).
  • hint-apply-color-scheme: If this element exists, the SVG will be colorized using the color scheme colors. Colorization is applied at 100%, and tapers off on either side, of an HSV color value/intensity of 127.
  • current-color-scheme: If a style element with this id exists it is replaced by a css-style with colors of the current colorscheme. See below for details.
  • [prefix]-hint-[direction]-margin: Use this optional hints if you want different margins than the borders size. The [prefix]- part is optional and identifies the prefix of the panel you want to specify the margins. [direction] can be either top, bottom, left or right and indicates the border you want to configure. For top and bottom margins the height of these hints are used, for left and right margins the width.
  • [prefix]-hint-compose-over-border: if this element is resent, the center element will be drawn with the same size as the total image, composed under the borders and shaped with the alpha mask frame, that has to be present in order to make work this hint(Optional).

Next there can be optionally another element called overlay (or [prefix]-overlay if to be appled to a frame with a different prefix) it will be rendered over the frame as a filigrane effects, with the rules given from the following mutually exclusive hints:

  • hint-overlay-random-pos it will be put at a random position, this works just for applet backgrounds
  • hint-overlay-tile tile the overlay
  • hint-overlay-stretch the overlay will be stretched
  • hint-overlay-pos-right align the overlay at right of the background rather than to the left
  • hint-overlay-pos-bottom align the overlay at bottom of the background rather than to the top

Inkscape extension

An Inkscape extension exists to automatically rename SVG elements with the above naming spec.

Using system colors

It is possible to apply colors from the color scheme to a graphic. A very easy way to reach this is by adding an element with the id hint-apply-color-scheme to the SVG, In this case the rendered graphic gets converted to monochrome and colorized by the window background color.

EditingSvgIcon.png

A more flexible solution is available by using CSS-styling. For this to work the SVG must have a style-element with the id current-color-scheme. Before the graphic is rendered this element gets replaced by a style containing classes where the color attribute is set to the corresponding system color. Currently the following classes are defined:

  • ColorScheme-Text
  • ColorScheme-Background
  • ColorScheme-Highlight
  • ColorScheme-ViewText
  • ColorScheme-ViewBackground
  • ColorScheme-ViewHover
  • ColorScheme-ViewFocus
  • ColorScheme-ButtonText
  • ColorScheme-ButtonBackground
  • ColorScheme-ButtonHover
  • ColorScheme-ButtonFocus

In order to apply a color from a class to an element, its fill or stroke attribute must be currentColor and of course the name of the wanted class has to be in the class-attribute. Special attention is needed on gradients, as neither the gradient-tags themselves nor the stop-tags accept classes. To still get the wanted result one can put a g-tag around them and apply the class to this.

In the Plasma-framework source repository, two useful tools are present:

  • currentColorFix.sh: fixes an error in the file format that inkscape often does that would break the coorect application of the stylesheet
  • apply-stylesheet.sh: looks in the SVG file for certain colors (by default from the Breeze palette) and replaces them with the corresponfing stylesheet class, automating a potential long and tedious job

Current Theme Elements

Themes get installed to share/plasma/desktoptheme. Each theme is stored in an own sub-folder by the name of the theme with the following file structure (all files can be in either .svg or .svgz format):

  • /dialogs: elements for dialogs
    • /background.svg: generic dialog background used by the screensaver password dialog, etc. See the section on backgrounds above for information on the required elements in this file.
      • hint-left-shadow: optional hints that say how big the shadow is
      • hint-top-shadow
      • hint-right-shadow
      • hint-bottom-shadow
  • /widgets: generic desktop widget background
    • /action-overlays.svg: overlays for icons to indicate actions
      • add-normal: icon used to add the parent icon to a selection of elements (used for instance in folderview), normal state, there are also add-hover and add-pressed
      • remove-normal: icon used to remove the parent icon to a selection of elements, normal state, there are also remove-hover and remove-pressed
      • open-normal: icon used to initialize tooltip on folderview widget, there are also open-hover and open-pressed
    • /analog_meter.svg: an analog gauge widget.
      • background: the body of the analog instrument
      • foreground: the pin where the hand rotates
      • pointer: the hand of the instrument
      • rotateminmax: how much the hand can rotate, the width is the maximum angle in degrees the height the minimum angle
      • label0: the rect for the first label
      • label1: the rect for the second label
    • /arrows.svg: arrows that match the theme. Four elements should exist in this SVG: up-arrow, down-arrow, left-arrow, right-arrow.
    • /background.svg: a background image for plasmoids. See the section on backgrounds above for information on the required elements in this file.
      • hint-left-shadow: optional hints that say how big the shadow is
      • hint-top-shadow
      • hint-right-shadow
      • hint-bottom-shadow
    • /bar_meter_horizontal.svg: an horizontal meter like a progressbar
      • background: background of the progressbar
      • foreground: overlay in the foreground of the progressbar
      • bar: the progressbar itself
      • background: a 9 pieces SVG with the background prefix, it replaces the background element if available
      • bar-active and bar-inactive: 9 pieces SVGs with the bar-active and bar-inactive prefixes, they replace the bar element when available, they will be drawn tiled
      • label0, label1 and label2: rects for 3 labels to be placed around
      • hint-bar-size: default height of the bar, if not present the default is taken from sum of heights of bar-inactive-top & bar-inactive-bottom
    • /bar_meter_vertical.svg: a vertical meter like a vertical progressbar. It has the same format of /bar_meter_horizontal.svg
    • /branding.svg: a little Plasma logo that can be customized by distributors as a branding element. Contains a single element called brilliant
    • /busywidget.svg: Used to indicate a busy state, it's a circular image that will be animated with a rotation.
      • busywidget: the main spinner
      • paused: the paused state
    • /button.svg: graphics elements for a button widget, it needs the following prefixes:
      • normal normal button
      • pressed pressed button
      • active button under mouse. Active can have ticker borders that would be rendered outside the widget. It's useful to do a glowing effect DEPRECATED: use hover instead
      • hover element that will be in the background of the widget, will act as a border (useful for glow effects)
      • shadow a shadow for the button, can be bigger than the button itself
      • focus keyboard focus rectangle superimposed to the button graphics
    • /calendar.svg: graphics for a calendar widget
      • weeksColumn: background for the vertical column with week numbers in it.
      • weekDayHeader: background for the row with week day names in it.
      • active: background for the day numbers of the current month.
      • inactive: background for the day numbers of the next and previous months.
      • hoverHighlight: background for the day under the mouse cursor.
      • today: border for the current day cell.
      • selected: border for the selected day cell.
      • red: border for holidays on sundays
      • green: border for holidays during week days
    • /clock.svg: an analog clock face. it must have the following named elements:
      • ClockFace: the background of the clock, usually containing the numbers, etc
      • HourHand: the hour hand, pointing down in the SVG
      • MinuteHand: the minute hand, pointing down in the SVG
      • SecondHand: the second hand, pointing down in the SVG
      • HourHandShadow, MinuteHandShadow and SecondHandShadow: drop shadows for the hands (optional)
      • HandCenterScrew: the "pin" that holds the hands together in the center
      • Glass: a final overlay which allows for things such as the appearance of glass
      • hint-square-clock: if present the shape of the clock will be square rather than round
      • hint-[hand(shadow)]-rotation-center-offset: the point of a hand (shadow) where it is "pinned" to the clock center, defined by the center of the hint, relative to the element position (can be outside the element), with [hand(shadow)] being hourhand, hourhandshadow, minutehand, minutehandshadow, secondhand, secondhandshadow, default is "(width/2, width/2)" from top-left of the hand (shadow) element (since Plasma 5.16)
      • hint-hands-shadow-offset-to-west or hint-hands-shadows-offset-to-east: horizontal offset of the hands shadows, default is 0 offset (since Plasma 5.16)
      • hint-hands-shadow-offset-to-north or hint-hands-shadow-offset-to-south: vertical offset of the hands shadows, default is 0 offset (since Plasma 5.16)
      • Note: In the SVG, the Hand elements as well as their optional Shadow counterparts must be oriented in a direction as the one indicating the time 6:30:30. The relative position of the Hand elements as well as their optional Shadow counterparts with respect to the center of ClockFace does not matter.
    • /configuration-icons: it's a set of simple icons that are meant to be shortcuts for configuration actions. Must contain the following elements:
      • close: a close icon
      • configure: a setup action
      • move
      • resize-vertical: resize in the y axis
      • resize-horizontal: resize in the x axis
      • size-diagonal-tl2br: resize diagonal, usually an arrow from top-left to bottom-right
      • size-diagonal-tr2bl: resize diagonal, usually an arrow from top-right to bottom-left
      • rotate
      • help
      • maximize
      • unmaximize
      • collapse: set something in a minimized, collapsed status
      • restore: restore from collapse status
      • status: refers to a status of something, logging or system monitoring in general
      • retourn-to-source: make detached extender items return to their owner applet
      • add and remove: specular actions, adding and removing for instance an item from a list
      • delete: the (potentially dangerous) action of deleting something
    • /containment-controls.svg: handles for the control used to resize the panel. The following elements are required.
      • maxslider maximum size slider, south position
      • minslider minimum size slider, south position
      • offsetslider positioning slider, south position
      • Each of the above elements must be present with north, south, east and west prefixes for each panel position.
      • There are also four backgrounds (north, south, east and west orientations) for the ruler widget itself in the "Backgrounds format", since the width of the widget is 100% the elements of left and right (or north and bottom if vertical) are not needed
    • /dragger.svg: meant to be a generic drag handle (not currently used but available). It needs to contain the same elements as other backgrounds, see the section about backgrounds above. In addition it needs the following element:
      • hint-preferred-icon-size: the size icons within the drag handle should get. The vertical size of the dragger is also derived from this: this size hint + the dragger's margins.
    • /frame.svg : a generic frame, used mostly for widget containers, to visually group widgets together. It must contain the following prefixes, for different 3d looks:
      • sunken
      • plain
      • raised
    • /glowbar.svg : a frame without a prefix, it represents a glow, it's used for instance in Plasma Desktop for the panel autohide unhide hint.
    • /line.svg : a simple line use to separate items in layouts, containe vertical-line and horizzontal-line elements
    • /lineedit.svg: it's a framesvg, used to style line edits, spinboxes and other similar fields, it must have the following prefixes
      • base: the background of the line edit
      • focus: will be drawn outside base, when the line edit has input focus
      • hover: will be drawn outside base, when the line edit is under the mouse
    • /listitem.svg: used for "opened"/clicked notifications
    • /monitor.svg : represents a screen, it's used in places such as the wallpaper config dialog. It contains a frame without prefixes and the following extra elements:
      • glass : glass reflection effect over the screen
      • base : a stand for the monitor
    • /notes.svg : design of note stickers, with 10 different color variants:
      • [color]-notes : colored note sticker with [color] one of: "white", "black", "red", "orange", "yellow", "green", "blue", "pink", "translucent", "translucent-light"
    • /pager.svg : graphic elements for the little screens of the pager, it must have 3 frames with the following prefixes:
      • normal : all virtual desktops
      • active : active virtual desktop
      • hover : virtual desktop under mouse
    • /panel-background.svg: the background image for panels.
      • If you want to create different background for panels located at the top, bottom, left or right, then also create sets of background elements with the following prefixes: north, south, west and east respectively. For example the center element of the left positioned panel's background should be named west-center.
      • All prefixes fallback to a no prefix version when not available
      • if a prefix called shadow is available, it will be used as a drop shadow for the panel when compositing is available.
    • /plot-background.svg: a background for plotter (graph) widgets, such as the plots in ksysguard
    • /scrollbar.svg : the classical elevator scrollbar, must have the following elemens : arrow-up, mouseover-arrow-up, sunken-arrow-up, same 3 elements for arrow-left, arrow-right and arrow-bottom. It can have an element called hint-scrollbar-size that says at what size the scrollbar should be rendered (width if vertical, height if horizontal). It must also have frames with the following prefixes:
      • slider
      • mouseover-slider
      • sunken-slider
      • background-vertical
      • background-horizontal
    • /scrollwidget: used by Plasma::ScrollWidget, it has a single prefix
      • border: a border used when the scrollbar is enabled
    • /slider.svg: used to theme sliders, it must have the following elements:
      • vertical-slider-line: the background for vertical sliders, it indicates how much the indicator can scroll
      • vertical-slider-handle: the handle for vertical sliders
      • vertical-slider-focus: background for the handle when it has input focus
      • vertical-slider-hover: background for the handle when it is under the mouse
      • groove: groove for the slider (since Plasma 4.8 replaces *-slider-line)
      • groove-highlight: highlight part of the groove (since Plasma 4.8 replaces *-slider-line)
      • horizontal-slider-line: the background for horizontal sliders
      • horizontal-slider-handle: the handle for horizontal sliders
      • horizontal-slider-focus: background for the handle when it has input focus
      • horizontal-slider-hover: background for the handle when it is under the mouse
    • /tabbar.svg: graphics elements for tabbars: contains 4 frames, each one for tabs in the possible orientations a tabbar can be relative to its contents, with the prefixes:
      • north
      • west
      • south
      • east
    • /tasks.svg: task item backgrounds for tasks. See the section on backgrounds above for information on the required elements in this file. The following element prefixes are required:
      • focus: background of focused task item
      • hover: background when the pointer hovers the task item. Focus and hover can have ticker borders that will be painted outside the task button, useful to make a glow effect.
      • attention: background when tasks item is trying to get attention
      • normal: background of normal, unfocused task item
      • minimized: background for minimized tasks
      • All the frames can be prefixed with "north-", "west-", "south-" or "east-" if the taskbar should have a different look at the 4 sides of the screen
      • The svg should contain elements of all five prefixes, if a prefix is missing that element will be not be drawn.
      • panel-north, panel-south, panel-west, panel-east : elements for the panel toolbox.
    • /tooltip.svg: background for tooltips used for instance in the taskbar and with icons. See the section on backgrounds above for information on the required elements in this file.
    • /translucentbackground.svg: a standard background image for plasmoids that for their nature are bigger and with not much text. In this case a translucent background looks better. It needs the same elements of background.svg in it. If this file is not present, the plasmoids that uses this will use background.svg instead.
    • /media-delegate.svg: intended to be used as delegate for media types: it contains a single prefix: picture.
    • /viewitem.svg: controls the background look of selections (results in KRunner, networks in network applet), it can have 4 elements of 9 parts each with prefix normal, hover, selected, selected+hover.
    • /toolbar.svg: used in the ToolBar QML component, can be used in custom applications in a similar way, contains a single frame without prefix.

"Opaque" folder

In the special subfolder opaque/ the same hierarchy can be found again: when compositing is disabled files in this folder are preferred over the corresponding ones listed above. Only background for top level windows are appropriate to go in this folder.

Since top-level windows will be shaped according to the transparency of the SVG and window shapes don't support alpha-blending, if the SVG has rounded borders they should have a shape that don't require anti-aliasing, like the following example.

No composite plasma svg.jpg

"translucent" folder

In the special folder translucent/ the same hierarchy is used as well: when the KWin Background Contrast effect is enabled the file under this folder will be used if found. As the opaque folder, only elements that will be rendered as window backgrounds should be present in this folder, so the dialogs folder, plus the panel and tooltip backgrounds. When is possible to blur the background of the window, the graphics can be more transparent, keeping the window text readable.

"icons" folder

In the folder icons/, SVG files that contain scalable icons for use with application status items (e.g. icons in the system tray) are contained.

Some of the common icons:

  • audio.svg
  • battery.svg
  • computer.svg
  • configure.svg
  • device.svg
  • input.svg
  • media.svg
  • network.svg
  • notification.svg
  • preferences.svg
  • start.svg
  • system.svg

The files are named the same as the icon theme name or their prefix, e.g. "audio.svg" or "audio-volume-high.svg". Multiple icons can be contained within a single file whose name must match the full icon name, e.g. "audio.svg" can contain elements named "audio-volume-muted", "audio-volume-low", "audio-volume-medium", and "audio-volume-high".

Theming Application Icons in the System Tray

Applications that use a function called setIconByName can have their icon in the system tray themed. Applications can have more than one icon (for example Konversation flashes between two different icons to highlight when your username is mentioned and Kpackagekit changes it's icon depending on the status of it's upgrade / installs). Theming these icons requires firstly that an application has been coded to use setIconByName, and secondly that you call your SVG object by the same name (use Ctrl+Shift-O in Inkscape). Then you can just put your .svg in share/plasma/desktoptheme/[themename]/icons.

The following is an attempt to list known icon names that may be themed by this method. Please add any other known icon names and the object ID here to help other people making themes:

  • Amarok
    • filename: amarok.svg
      • ID: amarok
  • audio (for kmix, veromix, a.o.)
    • filename: audio.svg
      • volume muted ID: audio-volume-muted
      • volume low ID: audio-volume-low
      • volume medium ID: audio-volume-medium
      • volume high ID: audio-volume-high
  • battery
    • filename: battery.svg
      • battery (always shown object) ID: Battery
      • on powerline ID: AcAdapter
      • no battery found ID: Unavailable
      • battery on 10% ID: Fill10
      • battery on 20% ID: Fill20
      • battery on 30% ID: Fill30
      • […]
      • battery on 90% ID: Fill90
      • battery on 100% ID: Fill100
  • device (the device-notifier)
    • filename: device.svg
      • ID: device-notifier
  • juk
    • filename: juk.svg
      • ID: juk
  • KGet
    • filename: kget.svg
      • ID: kget
  • Klipper
    • filename: klipper.svg
      • ID: klipper
  • Konversation
    • filename: konversation
      • ID: konversation
    • filename: konv_message.svg (new incomming message)
      • ID: konv_message
  • Kopete
    • filename: kopete.svg
      • öffline ID: kopete-offline
      • online ID: kopete
      • other statuses are not supported atm
  • Korgac
    • filename: korgac.svg
      • ID: korgac
  • Ktorrent
    • filename: ktorrent.svg
      • ID: ktorrent
  • message-indicator
    • filename: message-indicator.svg
      • standard ID: normal
      • new message ID: new
  • Nepomuk
    • filename: nepomuk.svg
      • ID: nepomuk
  • Network-management-plasmoid
    • filename: network.svg
      • wired online ID: network-wired-activated
      • wired offline ID: network-wired
      • wless offline ID: network-wireless-0
      • wless on 20% ID: network-wireless-20
      • wless on 25% ID: network-wireless-25
      • wless on 40% ID: network-wireless-40
      • wless on 50% ID: network-wireless-50
      • wless on 60% ID: network-wireless-60
      • wless on 75% ID: network-wireless-75
      • wless on 80% ID: network-wireless-80
      • wless on 100% ID: network-wireless-100
      • mobile broadband on 0% ID: network-mobile-0
      • mobile broadband on 20% ID: network-mobile-20
      • mobile broadband on 40% ID: network-mobile-40
      • mobile broadband on 60% ID: network-mobile-60
      • mobile broadband on 80% ID: network-mobile-80
      • mobile broadband on 100% ID: network-mobile-100
      • mobile broadband with access technology on 0% ID: network-mobile-0-technology (technology can be: none, gprs, edge, umts, hsdpa, hsupa, hspa, lte)
  • preferences (some apps like bluedevil, krandrtray, text-to-speech)
    • filename: preferences.svg
      • bluedevil online ID: preferences-system-bluetooth
      • bluedevil offline ID: preferences-system-bluetooth-inactive
      • text-to-speech ID: preferences-desktop-text-to-speech
      • krandrtray ID: preferences-desktop-display-randr
      • activity manager ID: preferences-activities
  • Printer applet
    • filename: printer.svg
      • ID: printer
  • Quassel IRC
    • filename: quassel.svg
      • quassel öffline ID: quassel-inactive
      • quassel online ID: quassel
      • quassel new message ID: quassel-message
  • KWallet
    • filename: wallet.svg
      • open ID: wallet-open
      • closed ID: wallet-closed

This page was last edited on 3 June 2019, at 19:29. Content is available under Creative Commons License SA 4.0 unless otherwise noted.