**'''/background.svg''': generic dialog background, used by the Run Command dialog, 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 sceensaver password dialog, etc. See the section on backgrounds above for information on the required elements in this file.

−

**'''/shutdowndlg.svg''': background for the log out dialog

+

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

−

**'''/shutdowndlgbuttonglow.svg''': an overlay for buttons on the log out dialog that is shown on mouse over

+

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

*'''/widgets''': generic desktop widget background

*'''/widgets''': generic desktop widget background

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

Line 107:

Line 112:

*** selection-rect: displayed when the icon is selected

*** selection-rect: displayed when the icon is selected

**'''/panel-background.svg''': the default background image for panels. See the section on backgrounds above for information on the required elements in this file.

**'''/panel-background.svg''': the default background image for panels. See the section on backgrounds above for information on the required elements in this file.

−

*** If you want to create different look for top, bottom, left and right panels, then, beside the default background elements, also create sets of elements with the following prefixes ''north-'', ''south-'', ''west-'' and ''east-''. For example the center element of the left positioned panel's background should be named ''west-center''. That elements will be loaded only when the panel size is 100% of the width (or height), otherwise the elements without prefix will be loaded (from KDE 4.1)

+

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

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

** '''/toolbox-button.svg''': the background for the desktop configuration toolbox button that sites at the edge of the desktop

** '''/toolbox-button.svg''': the background for the desktop configuration toolbox button that sites at the edge of the desktop

−

**'''/tasks.svg''': task item backgrounds for tasks (from KDE 4.1):

+

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

*** ''focus'': background of focused task item

*** ''hover'': background when the pointer hovers the task item

*** ''hover'': background when the pointer hovers the task item

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

−

*** the svg must contain elements of all four prefixes, if a prefix is missing that element will be drawn in a not themed way as fallback (the corresponding element from the default theme won't be used)

+

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

−

** '''/systemtray.svg''': a background for the system tray. it does not have prefixes (from KDE 4.1)

+

** '''/systemtray.svg''': a background for the system tray. it does not have prefixes (KDE 4.1 and later). See the section on backgrounds above for information on the required elements in this file.

−

** '''/containment-controls.svg''': handles for the ruler control used to resize the panel (from KDE 4.1), should contain the following elements

+

** '''/containment-controls.svg''': handles for the control used to resize the panel (KDE 4.1 and later). The following elements are required.

−

*** ''south-maxslider'' maximum size slider, south position

+

*** ''maxslider'' maximum size slider, south position

−

*** ''south-minslider'' minimum size slider, south position

+

*** ''minslider'' minimum size slider, south position

−

*** ''south-offsetslider'' positioning slider, south position

+

*** ''offsetslider'' positioning slider, south position

−

*** each one of the previous three elements must be present also with north-, east- and west prefixes

+

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

=="Opaque" folder==

=="Opaque" folder==

Revision as of 22:44, 21 May 2008

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("dialog/background");
svg.resize(size());

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.

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. (requires the latest SVN version of KDE, or 4.1)

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.

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. (requires the latest SVN version of KDE, or 4.1)

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

/widgets: generic desktop widget background

/background.svg: a background image for plasmoids. 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.

/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

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

/iconbutton.svg: backgrounds and overlays for icons that are clickable. can have any of the following named elements:

minibutton: the default appearance of the top-left button

minibutton-hover: the appearance of the top-left button when is hovered

minibutton-pressed: the appearance of the top-left button when is pressed

background: the default background, painted beneath the icon

background-hover: background when the mouse hovers the icon

background-pressed: background when the icon is pressed

foreground the default foreground, painted on top of the icon

foreground-hover: foreground when the mouse hovers the icon

foreground-pressed: foreground when the icon is pressed

selection-rect: displayed when the icon is selected

/panel-background.svg: the default background image for panels. See the section on backgrounds above for information on the required elements in this file.

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)

/plot-background.svg: a background for plotter (graph) widgets, such as the plots in ksysguard

/toolbox-button.svg: the background for the desktop configuration toolbox button that sites at the edge of the desktop

/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

attention: background when tasks item is trying to get attention

normal: background of normal, unfocused task item

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

/systemtray.svg: a background for the system tray. it does not have prefixes (KDE 4.1 and later). See the section on backgrounds above for information on the required elements in this file.

/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

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