< Development | Tutorials | Plasma4Revision as of 19:16, 8 July 2009 by Aseigo (talk | contribs) (→Colors)(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff) 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. Contents 1 Theme Location, Structure and Definition 2 Image Access 3 Wallpaper Access 4 Reaction to Theme Changes 5 Colors 6 Backgrounds format 7 Current Theme Elements 8 "Opaque" folder Theme Location, Structure and Definition 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 [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. Beneath this directory one will find the following file structure: colors: optional a configuration file defining a colorscheme that blends well with the images dialogs/': images for dialogs wallpapers/: wallpaper packages widgets/: images for widgets opaque/: optional directory containing images appropriate for non-compositing environments locolor/: optional directory containing images appropraite for locolor (e.g. 8 bit color) environments 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()); 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: [Wallpaper] defaultTheme=<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 KDE colorscheme file format and allows a theme to define what colors work best with its theme elements. The most common use 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 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 ForegroundLink used by dictionary and microblog widgets for unvisited links in the results text ForegroundVisited used by the dictonary and microblog widgets for visited links in the result text 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. 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) [prefix]-hint-margin-[direction]: 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. (Optional, From KDE 4.2 and later) 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 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. /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. /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. /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, KDE 4.1 and later) 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. /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) 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 /plot-background.svg: a background for plotter (graph) widgets, such as the plots in ksysguard /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. /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 top, 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. /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 /button.svg: graphics elements for a button widget (KDE 4.2 and later), it needs the followin 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 focus keyboard focus rectangle superimposed to the button graphics /extender-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. /extender-background.svgz: background for extenders. It needs the same elements as other backgrounds. /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 /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 (KDE 4.2 and later) hint-stretched-bar: make the progressbar background element stretched rather than tiled (KDE 4.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 (KDE4.2 and later) label0, label1 and label2: rects for 3 labels to be placed around /bar_meter_vertical.svg: a vertical meter like a vertical progressbar. It has the same format of /bar_meter_horizontal.svg /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 maximuze status refers to a status of something, logging or system monitoring in general /line.svgz: a simple line use to separate items in layouts (from KDE 4.3) horizontal-line: an horizontal line for vertical layouts vertical-line: a vertical line for horizontal layouts "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. Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/Plasma4/ThemeDetails&oldid=42994" Content is available under Creative Commons License SA 4.0 unless otherwise noted.