KDE 4.9 PyKDE API Reference

- KDE's Python API

# Theme Class Reference

`from PyKDE4.plasma import *`

Inherits: QObject
Namespace: Plasma

## Detailed Description

Theme plasma/theme.h <Plasma/Theme>

Interface to the Plasma theme

Accessed via Plasma.Theme.defaultTheme() e.g:

     QString imagePath = Plasma.Theme.defaultTheme()->imagePath("widgets/clock")

Plasma.Theme provides access to a common and standardized set of graphic elements stored in SVG format. This allows artists to create single packages of SVGs that will affect the look and feel of all workspace components.

Plasma.Svg uses Plasma.Theme internally to locate and load the appropriate SVG data. Alternatively, Plasma.Theme can be used directly to retrieve file system paths to SVGs by name.

## Enumerations

ColorRole | { TextColor, HighlightColor, BackgroundColor, ButtonTextColor, ButtonBackgroundColor, LinkColor, VisitedLinkColor, ButtonHoverColor, ButtonFocusColor, ViewTextColor, ViewBackgroundColor, ViewHoverColor, ViewFocusColor }
FontRole | { DefaultFont, DesktopFont, SmallestFont }

## Signals

| themeChanged ()

## Methods

| __init__ (self, QObject parent=0)
| __init__ (self, QString themeName, QObject parent=0)
QString | animationPath (self, QString name)
QColor | color (self, Plasma.Theme.ColorRole role)
KSharedPtr<KSharedConfig> | colorScheme (self)
bool | currentThemeHasImage (self, QString name)
bool | findInCache (self, QString key, QPixmap pix)
bool | findInCache (self, QString key, QPixmap pix, long lastModified)
bool | findInRectsCache (self, QString image, QString element, QRectF rect)
QFont | font (self, Plasma.Theme.FontRole role)
QFontMetrics | fontMetrics (self)
KUrl | homepage (self)
QString | imagePath (self, QString name)
| insertIntoCache (self, QString key, QPixmap pix)
| insertIntoCache (self, QString key, QPixmap pix, QString id)
| insertIntoRectsCache (self, QString image, QString element, QRectF rect)
| invalidateRectsCache (self, QString image)
QStringList | listCachedRectKeys (self, QString image)
| releaseRectsCache (self, QString image)
| setCacheLimit (self, int kbytes)
| setFont (self, QFont font, Plasma.Theme.FontRole role=Plasma.Theme.DefaultFont)
| setThemeName (self, QString themeName)
| setUseGlobalSettings (self, bool useGlobal)
| settingsChanged (self)
QString | styleSheet (self, QString css=QString())
QString | themeName (self)
int | toolTipDelay (self)
bool | useGlobalSettings (self)
bool | useNativeWidgetStyle (self)
QString | wallpaperPath (self, QSize size=QSize())
bool | windowTranslucencyEnabled (self)

## Static Methods

Plasma.Theme | defaultTheme ()
[KPluginInfo] | listThemeInfo ()
KSharedPtr<Plasma::PackageStructure> | packageStructure ()

## Signal Documentation

themeChanged | ( |  | ) |

Emitted when the user changes the theme. Stylesheet usage, colors, etc. should be updated at this point. However, SVGs should *not* be repainted in response to this signal; connect to Svg.repaintNeeded() instead for that, as Svg objects need repainting not only when themeChanged() is emitted; moreover Svg objects connect to and respond appropriately to themeChanged() internally, emitting Svg.repaintNeeded() at an appropriate time.

Signal syntax:
  `QObject.connect(source, SIGNAL("themeChanged()"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0
| ) |  |  |

Default constructor. Usually you want to use the singleton instead.

See also:
  defaultTheme

Parameters:

  | parent | the parent object

__init__ | ( | self, |
|  | QString | themeName,
|  | QObject | parent=0
| ) |  |  |

Construct a theme. Usually you want to use the singleton instead.

See also:
  defaultTheme

Parameters:

  | themeName | the name of the theme to create
  | parent | the parent object

Since:
  4.3

QString animationPath | ( | self, |
|  | QString | name
| ) |  |  |

Retrieves the path for the script file that contains a given Javascript animation.

Parameters:

  | the | name of the animation

Returns:
  the full path to the script file, or an emptry string on failure

Since:
  4.5

QColor color | ( | self, |
|  | Plasma.Theme.ColorRole | role
| ) |  |  |

Returns the text color to be used by items resting on the background

Parameters:

  | role | which role (usage pattern) to get the color for

KSharedPtr<KSharedConfig> colorScheme | ( |  | self ) |

Returns the color scheme configurationthat goes along this theme. This can be used with KStatefulBrush and KColorScheme to determine the proper colours to use along with the visual elements in this theme.

bool currentThemeHasImage | ( | self, |
|  | QString | name
| ) |  |  |

Checks if this theme has an image named in a certain way

Parameters:

  | name | the name of the file in the theme directory (without the ".svg" part or a leading slash)

Returns:
  true if the image exists for this theme

bool findInCache | ( | self, |
|  | QString | key,
|  | QPixmap | pix
| ) |  |  |

This is an overloaded member provided to check with file timestamp where cache is still valid.

Parameters:

  | key | the name to use in the cache for this image
  | pix | the pixmap object to populate with the resulting data if found
  | lastModified | if non-zero, the time stamp is also checked on the file, and must be newer than the timestamp to be loaded

Returns:
  true when pixmap was found and loaded from cache, false otherwise

Since:
  4.3

bool findInCache | ( | self, |
|  | QString | key,
|  | QPixmap | pix,
|  | long | lastModified
| ) |  |  |

This is an overloaded member provided to check with file timestamp where cache is still valid.

Parameters:

  | key | the name to use in the cache for this image
  | pix | the pixmap object to populate with the resulting data if found
  | lastModified | if non-zero, the time stamp is also checked on the file, and must be newer than the timestamp to be loaded

Returns:
  true when pixmap was found and loaded from cache, false otherwise

Since:
  4.3

bool findInRectsCache | ( | self, |
|  | QString | image,
|  | QString | element,
|  | QRectF | rect
| ) |  |  |

Tries to load the rect of a sub element from a disk cache

Parameters:

  | image | path of the image we want to check
  | element | sub element we want to retrieve
  | rect | output parameter of the element rect found in cache if not found or if we are sure it doesn't exist it will be QRect()

Returns:
  true if the element was found in cache or if we are sure the element doesn't exist

QFont font | ( | self, |
|  | Plasma.Theme.FontRole | role
| ) |  |  |

Returns the font to be used by themed items

Parameters:

  | role | which role (usage pattern) to get the font for

QFontMetrics fontMetrics | ( |  | self ) |

Returns the font metrics for the font to be used by themed items

KUrl homepage | ( |  | self ) |

Returns:
  the default homepage to use in conjunction with the branding svg content

Since:
  4.7

QString imagePath | ( | self, |
|  | QString | name
| ) |  |  |

Retrieve the path for an SVG image in the current theme.

Parameters:

  | name | the name of the file in the theme directory (without the ".svg" part or a leading slash)

Returns:
  the full path to the requested file for the current theme

insertIntoCache | ( | self, |
|  | QString | key,
|  | QPixmap | pix
| ) |  |  |

Insert specified pixmap into the cache. If the cache already contains pixmap with the specified key then it is overwritten. The actual insert is delayed for optimization reasons and the id parameter is used to discard repeated inserts in the delay time, useful when for instance the graphics to inser comes from a quickly resizing object: the frames between the start and destination sizes aren't useful in the cache and just cause overhead.

Parameters:

  | key | the name to use in the cache for this pixmap
  | pix | the pixmap data to store in the cache
  | id | a name that identifies the caller class of this function in an unique fashion. This is needed to limit disk writes of the cache. If an image with the same id changes quickly, only the last size where insertIntoCache was called is actually stored on disk

Since:
  4.3

insertIntoCache | ( | self, |
|  | QString | key,
|  | QPixmap | pix,
|  | QString | id
| ) |  |  |

Insert specified pixmap into the cache. If the cache already contains pixmap with the specified key then it is overwritten. The actual insert is delayed for optimization reasons and the id parameter is used to discard repeated inserts in the delay time, useful when for instance the graphics to inser comes from a quickly resizing object: the frames between the start and destination sizes aren't useful in the cache and just cause overhead.

Parameters:

  | key | the name to use in the cache for this pixmap
  | pix | the pixmap data to store in the cache
  | id | a name that identifies the caller class of this function in an unique fashion. This is needed to limit disk writes of the cache. If an image with the same id changes quickly, only the last size where insertIntoCache was called is actually stored on disk

Since:
  4.3

insertIntoRectsCache | ( | self, |
|  | QString | image,
|  | QString | element,
|  | QRectF | rect
| ) |  |  |

Inserts a rectangle of a sub element of an image into a disk cache

Parameters:

  | image | path of the image we want to insert information
  | element | sub element we want insert the rect
  | rect | element rectangle

invalidateRectsCache | ( | self, |
|  | QString | image
| ) |  |  |

Discards all the information about a given image from the rectangle disk cache

Parameters:

  | image | the path to the image the cache is assoiated with

QStringList listCachedRectKeys | ( | self, |
|  | QString | image
| ) |  |  |

Returns a list of all keys of cached rects for the given image.

Parameters:

  | image | path of the image for which the keys should be returned

Returns:
  a QStringList whose elements are the entry keys in the rects cache

Since:
  4.6

releaseRectsCache | ( | self, |
|  | QString | image
| ) |  |  |

Frees up memory used by cached information for a given image without removing the permenant record of it on disk.

See also:
  invalidateRectsCache

Parameters:

  | image | the path to the image the cache is assoiated with

setCacheLimit | ( | self, |
|  | int | kbytes
| ) |  |  |

Sets the maximum size of the cache (in kilobytes). If cache gets bigger the limit then some entries are removed Setting cache limit to 0 disables automatic cache size limiting.

Note that the cleanup might not be done immediately, so the cache might temporarily (for a few seconds) grow bigger than the limit.

setFont | ( | self, |
|  | QFont | font,
|  | Plasma.Theme.FontRole | role=Plasma.Theme.DefaultFont
| ) |  |  |

Sets the default font to be used with themed items. Defaults to the application wide default font.

Parameters:

  | font | the new font
  | role | which role (usage pattern) to set the font for

setThemeName | ( | self, |
|  | QString | themeName
| ) |  |  |

Sets the current theme being used.

setUseGlobalSettings | ( | self, |
|  | bool | useGlobal
| ) |  |  |

Tells the theme whether to follow the global settings or use application specific settings

Parameters:

  | useGlobal | pass in true to follow the global settings

settingsChanged | ( |  | self ) |

Notifies the Theme object that the theme settings have changed and should be read from the config file

QString styleSheet | ( | self, |
|  | QString | css=QString()
| ) |  |  |

Provides a Plasma.Theme-themed stylesheet for hybrid (web / native Plasma) widgets.

You can use this method to retrieve a basic default stylesheet, or to theme your custom stylesheet you use for example in Plasma.WebView. The QString you can pass into this method does not have to be a valid stylesheet, in fact you can use this method to replace color placeholders with the theme's color in any QString.

In order to use this method with a custom stylesheet, just put for example %textcolor in your QString and it will be replaced with the theme's text (or foreground) color.

Just like in many other methods for retrieving theme information, do not forget to update your stylesheet upon the themeChanged() signal.

The following tags will be replaced by corresponding colors from Plasma.Theme:

%textcolor %backgroundcolor %buttonbackgroundcolor

%link %activatedlink %hoveredlink %visitedlink

%fontfamily %fontsize %smallfontsize

Parameters:

  | css | a stylesheet to theme, leave empty for a default stylesheet containing theming for some commonly used elements, body text and links, for example.

Returns:
  a piece of CSS that sets the most commonly used style elements to a theme matching Plasma.Theme.

Since:
  4.5

QString themeName | ( |  | self ) |

Returns:
  the name of the theme.

int toolTipDelay | ( |  | self ) |

Returns:
  the default tool tip delay; -1 means "no tooltips"

bool useGlobalSettings | ( |  | self ) |

Returns:
  true if the global settings are followed, false if application specific settings are used.

bool useNativeWidgetStyle | ( |  | self ) |

Returns:
  true if the native widget styles should be used instead of themed widgets. Defaults is false.

QString wallpaperPath | ( | self, |
|  | QSize | size=QSize()
| ) |  |  |

Retrieves the default wallpaper associated with this theme.

Parameters:

  | size | the target height and width of the wallpaper; if an invalid size is passed in, then a default size will be provided instead.

Returns:
  the full path to the wallpaper image

bool windowTranslucencyEnabled | ( |  | self ) |

Returns if the window manager effects (e.g. translucency, compositing) is active or not

## Static Method Documentation

Plasma.Theme defaultTheme | ( |  | ) |

Singleton pattern accessor

[KPluginInfo] listThemeInfo | ( |  | ) |

Returns:
  a list of all known themes

Since:
  4.3

KSharedPtr<Plasma::PackageStructure> packageStructure | ( |  | ) |

Returns:
  a package structure representing a Theme

## Enumeration Documentation

ColorRole

Enumerator:

  TextColor = 0 |
  HighlightColor = 1 |
  BackgroundColor = 2 |
  ButtonTextColor = 4 |
  ButtonBackgroundColor = 8 |
  LinkColor = 16 |
  VisitedLinkColor = 32 |
  ButtonHoverColor = 64 |
  ButtonFocusColor = 128 |
  ViewTextColor = 256 |
  ViewBackgroundColor = 512 |
  ViewHoverColor = 1024 |
  ViewFocusColor = 2048 |

FontRole

Enumerator:

  DefaultFont = 0 |
  DesktopFont |
  SmallestFont |