(→Current Theme Elements) |
(→Current Theme Elements) |
||
(30 intermediate revisions by 10 users not shown) | |||
Line 8: | Line 8: | ||
Themes are stored in {{path|share/apps/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 {{path|share/apps/desktoptheme}}. A theme is described by a .desktop file in {{path|share/apps/desktoptheme}}. The contents of which might look like this: | ||
− | < | + | <syntaxhighlight lang="text"> |
[Desktop Entry] | [Desktop Entry] | ||
Name=Oxygen | Name=Oxygen | ||
Line 22: | Line 22: | ||
X-KDE-PluginInfo-License=GPL | X-KDE-PluginInfo-License=GPL | ||
X-KDE-PluginInfo-EnabledByDefault=true | X-KDE-PluginInfo-EnabledByDefault=true | ||
− | </ | + | </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 must contain the name of the subdirectory in {{path|share/apps/desktoptheme}} where the SVG files for this theme exist. | ||
Line 29: | Line 29: | ||
* '''colors''': optional a configuration file defining a colorscheme that blends well with the images | * '''colors''': optional a configuration file defining a colorscheme that blends well with the images | ||
− | * '''dialogs/ | + | * '''dialogs/''': images for dialogs |
* '''wallpapers/''': wallpaper packages | * '''wallpapers/''': wallpaper packages | ||
* '''widgets/''': images for widgets | * '''widgets/''': images for widgets | ||
Line 40: | Line 40: | ||
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"> |
Plasma::Theme theme; | Plasma::Theme theme; | ||
QSvgRenderer svg(theme.image("dialogs/background")); | QSvgRenderer svg(theme.image("dialogs/background")); | ||
− | </ | + | </syntaxhighlight> |
− | 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! | + | 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! |
− | < | + | <syntaxhighlight lang="cpp-qt"> |
Plasma::Svg svg("dialogs/background"); | Plasma::Svg svg("dialogs/background"); | ||
svg.resize(size()); | svg.resize(size()); | ||
− | </ | + | </syntaxhighlight> |
== Wallpaper Access == | == Wallpaper Access == | ||
Line 58: | Line 58: | ||
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, 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: | ||
− | < | + | <syntaxhighlight lang="text"> |
[Wallpaper] | [Wallpaper] | ||
− | + | defaultWallpaperTheme=<name of default wallpaper package> | |
defaultFileSuffix=<wallpaper file suffix, e.g. .jpg> | defaultFileSuffix=<wallpaper file suffix, e.g. .jpg> | ||
defaultWidth=<width in pixels of default wallpaper file> | defaultWidth=<width in pixels of default wallpaper file> | ||
defaultHeight=<height in pixels of default wallpaper file> | defaultHeight=<height in pixels of default wallpaper file> | ||
− | </ | + | </syntaxhighlight> |
== Animations == | == Animations == | ||
Line 130: | Line 130: | ||
* '''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. (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-[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) | * '''[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) | ||
Line 136: | Line 137: | ||
* '''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 (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) | * '''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 <tt><rect id="hint-apply-color-scheme" width="1" height="1" fill="none" /></tt> below your css-code but before the closing <tt></style></tt> | ||
+ | |||
+ | If you don't want to bother with the source code of your graphics, you can use the tool svgmod for easily applying system colors. See [https://projects.kde.org/projects/playground/devtools/svgmod here]. | ||
== Current Theme Elements == | == Current Theme Elements == | ||
Line 146: | Line 168: | ||
*'''/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 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. | + | *** '''hint-left-shadow''': from KDE 4.10: optional hints that say how big the shadow is |
+ | *** '''hint-top-shadow''' | ||
+ | *** '''hint-right-shadow''' | ||
+ | *** '''hint-bottom-shadow''' | ||
+ | **'''/krunner.svg''': dialog background, used by the Run Command. Please note, that this is used only when <menuchoice>Positioning</menuchoice> is set to <menuchoice>Free floating window</menuchoice>, '''not''' <menuchoice>Top edge of screen</menuchoice> (which is default). 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 | **'''/shutdowndlg.svg''': background and buttons for the log out dialog | ||
***''background'': background for the logout dialog | ***''background'': background for the logout dialog | ||
Line 158: | Line 184: | ||
*** ''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 | ||
Line 167: | Line 194: | ||
**'''/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-top-shadow''' | ||
+ | *** '''hint-right-shadow''' | ||
+ | *** '''hint-bottom-shadow''' | ||
** '''/bar_meter_horizontal.svg''': an horizontal meter like a progressbar | ** '''/bar_meter_horizontal.svg''': an horizontal meter like a progressbar | ||
***''background'': background of the progressbar | ***''background'': background of the progressbar | ||
Line 177: | Line 208: | ||
** '''/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.svgz''': a little KDE 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'': the main spinner | *** ''busywidget'': the main spinner | ||
*** ''paused'': the paused state | *** ''paused'': the paused state | ||
Line 223: | Line 254: | ||
*** ''status'': refers to a status of something, logging or system monitoring in general | *** ''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 | *** ''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 (KDE 4.1 and later). The following elements are required. | ** '''/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 | *** ''maxslider'' maximum size slider, south position | ||
Line 232: | Line 265: | ||
*** ''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. | ||
** '''/extender-background.svgz''': background for extenders. It needs the same elements as other backgrounds. | ** '''/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 | + | ** '''/extender-dragger.svgz''': Same as dragger.svgz. Drag handle for extenders (like the notification applet, 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. | *** ''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: | ** '''/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'' | *** ''sunken'' | ||
Line 245: | Line 279: | ||
*** ''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) | ||
** '''/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.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 | *** ''glass'' : glass reflection effect over the screen | ||
Line 254: | Line 289: | ||
**'''/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''. (KDE 4.1 and later) | ||
− | *** When the panel is not 100% wide/tall the north, south | + | *** 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. |
*** 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. | ||
** '''/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'. It must also have frames with the following prefixes: | + | ** '''/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: |
*** ''slider'' | *** ''slider'' | ||
*** ''mouseover-slider'' | *** ''mouseover-slider'' | ||
Line 270: | Line 306: | ||
*** ''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 (since KDE 4.4) | ||
*** ''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 (since KDE 4.4) | ||
+ | *** ''groove'': groove for the slider (since KDE 4.8 replaces *-slider-line) | ||
+ | *** ''groove-highlight'': highlight part of the groove (since KDE 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 | ||
Line 287: | Line 325: | ||
** '''/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. | ||
+ | ** '''/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''. | ||
+ | ** '''/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. | ||
=="Opaque" folder== | =="Opaque" folder== | ||
Line 295: | Line 336: | ||
[[Image:No_composite_plasma_svg.jpg]] | [[Image:No_composite_plasma_svg.jpg]] | ||
+ | |||
+ | =="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. | ||
+ | |||
+ | =="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. | ||
+ | |||
+ | 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 {{path|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. Please add any other known icon names and the object ID here to help other people making themes: | ||
+ | |||
+ | * Amarok | ||
+ | ** filename: '''amarok.svgz''' | ||
+ | *** ID: '''amarok''' | ||
+ | * audio (for kmix, veromix, a.o.) | ||
+ | ** filename: '''audio.svgz''' | ||
+ | *** 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.svgz''' | ||
+ | *** battery (always shown object) ID: '''Battery''' | ||
+ | *** on powerline ID: '''AcAdapter''' | ||
+ | *** no battery found ID: '''Unavailable''' | ||
+ | *** battery on 20% ID: '''Fill20''' | ||
+ | *** battery on 40% ID: '''Fill40''' | ||
+ | *** battery on 60% ID: '''Fill60''' | ||
+ | *** battery on 80% ID: '''Fill80''' | ||
+ | *** battery on 100% ID: '''Fill100''' | ||
+ | * device (the device-notifier) | ||
+ | ** filename: '''device.svgz''' | ||
+ | *** ID: '''device-notifier''' | ||
+ | * juk | ||
+ | ** filename: '''juk.svgz''' | ||
+ | *** ID: '''juk''' | ||
+ | * KGet | ||
+ | ** filename: '''kget.svgz''' | ||
+ | *** ID: '''kget''' | ||
+ | * Klipper | ||
+ | ** filename: '''klipper.svgz''' | ||
+ | *** ID: '''klipper''' | ||
+ | * Konversation | ||
+ | ** filename: '''konversation''' | ||
+ | *** ID: '''konversation''' | ||
+ | ** filename: '''konv_message.svgz''' (new incomming message) | ||
+ | *** ID: '''konv_message''' | ||
+ | * Kopete | ||
+ | ** filename: '''kopete.svgz''' | ||
+ | *** öffline ID: '''kopete-offline''' | ||
+ | *** online ID: '''kopete''' | ||
+ | *** other statuses are not supported atm | ||
+ | * Korgac | ||
+ | ** filename: '''korgac.svgz''' | ||
+ | *** ID: '''korgac''' | ||
+ | * Ktorrent | ||
+ | ** filename: '''ktorrent.svgz''' | ||
+ | *** ID: '''ktorrent''' | ||
+ | * message-indicator | ||
+ | ** filename: '''message-indicator.svgz''' | ||
+ | *** standard ID: '''normal''' | ||
+ | *** new message ID: '''new''' | ||
+ | * Nepomuk | ||
+ | ** filename: '''nepomuk.svgz''' | ||
+ | *** ID: '''nepomuk''' | ||
+ | * Network-management-plasmoid | ||
+ | ** filename: '''network.svgz''' | ||
+ | *** 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''' | ||
+ | * preferences (some apps like bluedevil, krandrtray, text-to-speech) | ||
+ | ** filename: '''preferences.svgz''' | ||
+ | *** 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.svgz''' | ||
+ | *** ID: '''printer''' | ||
+ | * Quassel IRC | ||
+ | ** filename: '''quassel.svgz''' | ||
+ | *** quassel öffline ID: '''quassel_inactive''' ("quassel-inactive" in kde 4.10) | ||
+ | *** quassel online ID: '''quassel''' | ||
+ | *** quassel new message ID: '''quassel_message''' ("quassel-message" in kde 4.10) | ||
+ | * KWallet | ||
+ | ** filename: '''wallet.svgz''' | ||
+ | *** open ID: '''wallet-open''' | ||
+ | *** 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. |
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 Creating a Plasma Theme.
Themes are stored in share/apps/desktoptheme. 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
X-KDE-PluginInfo-Email=kde-artists@kde.org
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.
Beneath this directory one will find the following file structure:
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());
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:
[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>
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.
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.
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 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:
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:
Note that some of these may end up folded back into Plasma::Theme properly at some point.
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:
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:
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:
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:
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>
If you don't want to bother with the source code of your graphics, you can use the tool svgmod for easily applying system colors. See here.
Themes get installed to share/apps/desktoptheme. Each theme is stored in a subdirectory with the following file structure
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.
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.
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:
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.
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. Please add any other known icon names and the object ID here to help other people making themes:
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.