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

Jump to: navigation, search
(Current Theme Elements)
Line 45: Line 45:
 
== Reaction to Theme Changes ==
 
== Reaction to Theme Changes ==
 
If you use Plasma::Svg, changes to the theme are automatically picked up. Otherwise, you can connect to the <tt>changed()</tt> signal in the Plasma::Theme class. This signal is emitted whenever the theme is changed.
 
If you use Plasma::Svg, changes to the theme are automatically picked up. Otherwise, you can connect to the <tt>changed()</tt> signal in the Plasma::Theme class. This signal is emitted whenever the theme is changed.
 +
 +
== Backgrounds ==
 +
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
 +
 +
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
  
 
== Current Theme Elements ==
 
== Current Theme Elements ==
Line 51: Line 67:
  
 
*'''/dialogs''': elements for dialogs
 
*'''/dialogs''': elements for dialogs
**'''/background.svg''': generic dialog background, used by the Run Command dialog, the sceensaver password dialog, etc
+
**'''/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.
 
**'''/shutdowndlg.svg''': background for the log out dialog
 
**'''/shutdowndlg.svg''': background for the log out dialog
 
**'''/shutdowndlgbuttonglow.svg''': an overlay for buttons on the log out dialog that is shown on mouse over
 
**'''/shutdowndlgbuttonglow.svg''': an overlay for buttons on the log out dialog that is shown on mouse over
 
*'''/widgets''': generic desktop widget background
 
*'''/widgets''': generic desktop widget background
**'''/background.svg''': a background image for plasmoids.
+
**'''/background.svg''': a background image for plasmoids. See the section on backgrounds above for information on the required elements in this file.
 
**'''/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
*** 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
 
** '''/iconbutton.svg''': backgrounds and overlays for icons that are clickable. can have any of the following named elements:
 
** '''/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'': the default appearance of the top-left button
*** minibutton-hover: the appearance of the top-left button when is hovered
+
*** ''minibutton-hover'': the appearance of the top-left button when is hovered
*** minibutton-pressed: the appearance of the top-left button when is pressed
+
*** ''minibutton-pressed'': the appearance of the top-left button when is pressed
*** background: the default background, painted beneath the icon
+
*** ''background'': the default background, painted beneath the icon
*** background-hover: background when the mouse hovers the icon
+
*** ''background-hover'': background when the mouse hovers the icon
*** background-pressed: background when the icon is pressed
+
*** ''background-pressed'': background when the icon is pressed
*** foreground: the default foreground, painted on top of the icon
+
*** ''foreground'' the default foreground, painted on top of the icon
*** foreground-hover: foreground when the mouse hovers the icon
+
*** ''foreground-hover'': foreground when the mouse hovers the icon
 
*** foreground-pressed: foreground when the icon is pressed
 
*** foreground-pressed: foreground when the icon is pressed
 
*** 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.
 
** '''/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

Revision as of 19:26, 6 December 2007

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.

See also Plasma widgets.

Theme Storage

A theme is described by a .desktop file in share/apps/desktoptheme. The contents of which might look like this:

[Desktop Entry] Name=Oxygen Comment=Theme done in the Oxygen style

X-KDE-PluginInfo-Author=The Oxygen Project [email protected] X-KDE-PluginInfo-Name=default X-KDE-PluginInfo-Version=pre0.1 X-KDE-PluginInfo-Website=http://plasma.kde.org X-KDE-PluginInfo-Category= X-KDE-PluginInfo-Depends= X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=true

The X-KDE-PluginInfo-Name entry must contain the name of the subdirectory in share/apps/desktoptheme where the SVG files for this theme exist.

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("dialog/background"));

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.

Backgrounds

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

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

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 Run Command dialog, 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
    • /shutdowndlgbuttonglow.svg: an overlay for buttons on the log out dialog that is shown on mouse over
  • /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.
    • /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.
    • /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

Content is available under Creative Commons License SA 4.0 unless otherwise noted.