*** ''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''

+

*** ''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.

** '''/analog_meter.svg''': an analog gauge widget.

***''background'': the body of the analog instrument

***''background'': the body of the analog instrument

Revision as of 23:53, 15 January 2011

libplasma 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.

It is generally recommended to use Plasma::Svg instead of QSvgRenderer directly, however. 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 wallpapers to be used with the theme. These wallpapers must appear in the 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:

Animations

Animations written in Javascript can be included in the animations directory within the theme. To learn how to create such animations and expose them in your theme, visit the Javascript Animations tutorial.

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 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.

Make a new colorscheme using the editor in SystemSettings>>Appearance>>Colors.

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::HighlightCoor

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

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 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:

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. (Optional, From KDE 4.1 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. (Optional, From KDE 4.6 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. (Optional, From KDE 4.2 and later)

[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)

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:

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 (from KDE 4.4)

hint-overlay-pos-bottom align the overlay at bottom of the background rather than to the top (from KDE 4.4)

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.

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:

ColorScheme-Text

ColorScheme-Background

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 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.

Hint: If you want to use this new feature and still be able to use the graphics on older versions, you can set the color for ColorScheme-Background to #7f7f7f and place a <rect id="hint-apply-color-scheme" width="1" height="1" fill="none" /> below your css-code but before the closing </style>

Current Theme Elements

Themes get installed to share/apps/desktoptheme. Each theme is stored in a subdirectory with the following file structure

/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.

/krunner.svg: dialog background, used by the Run Command. See the section on backgrounds above for information on the required elements in this file.

/shutdowndlg.svg: background and buttons for the log out dialog

background: background for the logout dialog

button-normal: button background

button-hover: button background on cursor hover

button-small-normal: small button background

button-small-hover: small button background on cursor hover

/kickoff.svgz : background for the kickoff launcher, needs a frame, with the prefix 'plain'

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

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.

/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:

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

/containment-controls.svg: handles for the control used to resize the panel (KDE 4.1 and later). 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.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:

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.

/extender-background.svgz: background for extenders. It needs the same elements as other backgrounds.

/extender-dragger.svgz: Same as dragger.svgz. Drag handle for extenders (like the popup date of clock applets, KDE 4.2 and later). 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.

Since KDE 4.6 it contains two optional prefixes: grouped for extender items contained in extender groups and root for root extender items. The version without prefix must still exist and is still used for extenders that don't have a stacked appearance.

/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:

sunken

plain

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.

/identiconshapes.svgz : shapes for the auto-generation of the activity icons, they must be named from Shape1 to Shape32. Since KDE SC 4.5

/line.svgz : a simple line use to separate items in layouts, containe vertical-line and horizzontal-line elements (since KDE 4.3)

/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

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

/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:

glass : glass reflection effect over the screen

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:

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. (KDE 4.1 and later)

When the panel is not 100% wide/tall the north, south etch prefixes becomes north-mini etc. (KDE 4.2 and later)

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.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'. 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 (KDE4.4 and later)

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:

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 (since KDE 4.4)

vertical-slider-hover: background for the handle when it is under the mouse (since KDE 4.4)

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 (since KDE 4.4)

horizontal-slider-hover: background for the handle when it is under the mouse (since KDE 4.4)

/systemtray.svg: a background for the system tray (KDE 4.1 and later). See the section on backgrounds above for information on the required elements in this file. Since KDE 4.2 it contains also the lastelements prefix, used for elements in the last position of the systray and the four elements expander-right up, left and bottom, used for the icon that shows/hides the other systray icons. Since KDE 4.3 there are the horizontal-separator and vertical-separator used as a border to separe the last elements.

/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:

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.

attention: background when tasks item is trying to get attention

normal: background of normal, unfocused task item

minimized: background for minimized tasks

The svg should contain elements of all five prefixes, if a prefix is missing that element will be not be drawn.

/toolbox.svgz : graphical elements for the desktop toolbox, it must have a frame without prefixes plus those following elements:

/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.

"Opaque" folder

In the folder 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.

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.

"translucent" folder

In the folder 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.

"icons" folder

In the folder 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.

The default theme contains the following SVGs:

audio.svgz

battery.svgz

device.svgz

klipper.svgz

kwalletmanager.svgz

nepomuk.svgz

network.svgz

notification.svgz

preferences.svgz

wallet.svgz

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.

Theming Application Icons in the Systemtray

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 share/apps/desktoptheme/default/icons (changing default to your theme folder name).

The following is an attempt to list known icon names that may be themed by this method: