Plasma::Theme Class Reference

#include <Plasma/Theme>

Inheritance diagram for Plasma::Theme:

Public Types
enum	ColorRole {   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 }
enum	FontRole { DefaultFont = 0, DesktopFont, SmallestFont }

Public Slots
void	settingsChanged ()

Signals
void	themeChanged ()

Public Member Functions
	Theme (QObject *parent=0)
	Theme (const QString &themeName, QObject *parent=0)
	~Theme ()
Q_INVOKABLE QString	animationPath (const QString &name) const
Q_INVOKABLE QColor	color (ColorRole role) const
Q_INVOKABLE KSharedConfigPtr	colorScheme () const
Q_INVOKABLE bool	currentThemeHasImage (const QString &name) const
bool	findInCache (const QString &key, QPixmap &pix)
bool	findInCache (const QString &key, QPixmap &pix, unsigned int lastModified)
bool	findInRectsCache (const QString &image, const QString &element, QRectF &rect) const
Q_INVOKABLE QFont	font (FontRole role) const
Q_INVOKABLE QFontMetrics	fontMetrics () const
KUrl	homepage () const
Q_INVOKABLE QString	imagePath (const QString &name) const
void	insertIntoCache (const QString &key, const QPixmap &pix)
void	insertIntoCache (const QString &key, const QPixmap &pix, const QString &id)
void	insertIntoRectsCache (const QString &image, const QString &element, const QRectF &rect)
void	invalidateRectsCache (const QString &image)
QStringList	listCachedRectKeys (const QString &image) const
void	releaseRectsCache (const QString &image)
void	setCacheLimit (int kbytes)
Q_INVOKABLE void	setFont (const QFont &font, FontRole role=DefaultFont)
void	setThemeName (const QString &themeName)
void	setUseGlobalSettings (bool useGlobal)
Q_INVOKABLE QString	styleSheet (const QString &css=QString()) const
QString	themeName () const
int	toolTipDelay () const
bool	useGlobalSettings () const
bool	useNativeWidgetStyle () const
Q_INVOKABLE QString	wallpaperPath (const QSize &size=QSize()) const
Q_INVOKABLE bool	windowTranslucencyEnabled () const

Static Public Member Functions
static Theme *	defaultTheme ()
static KPluginInfo::List	listThemeInfo ()
static PackageStructure::Ptr	packageStructure ()

Properties
QString	themeName

Detailed Description

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.

Definition at line 56 of file theme.h.

Member Enumeration Documentation

enum Plasma::Theme::ColorRole

Enumerator
TextColor	the text color to be used by items resting on the background
HighlightColor	the text higlight color to be used by items resting on the background
BackgroundColor	the default background color
ButtonTextColor
ButtonBackgroundColor	text color for buttons
LinkColor	background color for buttons
VisitedLinkColor	color for clickable links
ButtonHoverColor	color visited clickable links
ButtonFocusColor	color for hover effect on buttons
ViewTextColor	color for focus effect on buttons
ViewBackgroundColor	text color for views
ViewHoverColor	background color for views
ViewFocusColor	color for hover effect on view

Definition at line 62 of file theme.h.

enum Plasma::Theme::FontRole

Enumerator
DefaultFont	The standard text font.
DesktopFont	The standard text font.
SmallestFont	The smallest readable font.

Definition at line 79 of file theme.h.

Constructor & Destructor Documentation

Plasma::Theme::Theme ( QObject *  parent = 0 )

explicit

Default constructor.

Usually you want to use the singleton instead.

See also

defaultTheme

Parameters

parent

the parent object

Definition at line 549 of file theme.cpp.

Plasma::Theme::Theme ( const QString &  themeName, QObject *  parent = 0  )

explicit

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

Definition at line 560 of file theme.cpp.

Plasma::Theme::~Theme

(

)

Definition at line 575 of file theme.cpp.

Member Function Documentation

QString Plasma::Theme::animationPath

(

const QString &

name

)

const

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

Definition at line 841 of file theme.cpp.

QColor Plasma::Theme::color

(

ColorRole

role

)

const

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

Parameters

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

Definition at line 918 of file theme.cpp.

KSharedConfigPtr Plasma::Theme::colorScheme

(

)

const

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.

Definition at line 913 of file theme.cpp.

bool Plasma::Theme::currentThemeHasImage

(

const QString &

name

)

const

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

Definition at line 902 of file theme.cpp.

Theme * Plasma::Theme::defaultTheme ( )

static

Singleton pattern accessor.

Definition at line 544 of file theme.cpp.

bool Plasma::Theme::findInCache	(	const QString &	key,
		QPixmap &	pix
	)

Tries to load pixmap with the specified key from cache.

Parameters

key	the name to use in the cache for this image
pix	the pixmap object to populate with the resulting data if found

Returns

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

Definition at line 1025 of file theme.cpp.

bool Plasma::Theme::findInCache	(	const QString &	key,
		QPixmap &	pix,
		unsigned int	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

Definition at line 1045 of file theme.cpp.

bool Plasma::Theme::findInRectsCache	(	const QString &	image,
		const QString &	element,
		QRectF &	rect
	)		const

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

Definition at line 1076 of file theme.cpp.

QFont Plasma::Theme::font

(

FontRole

role

)

const

Returns the font to be used by themed items.

Parameters

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

Definition at line 970 of file theme.cpp.

QFontMetrics Plasma::Theme::fontMetrics

(

)

const

Returns

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

Definition at line 992 of file theme.cpp.

KUrl Plasma::Theme::homepage

(

)

const

Returns

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

Since

4.7

Definition at line 1188 of file theme.cpp.

QString Plasma::Theme::imagePath

(

const QString &

name

)

const

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

Definition at line 794 of file theme.cpp.

void Plasma::Theme::insertIntoCache	(	const QString &	key,
		const QPixmap &	pix
	)

Insert specified pixmap into the cache.

If the cache already contains pixmap with the specified key then it is overwritten.

Parameters

key	the name to use in the cache for this pixmap
pix	the pixmap data to store in the cache

Definition at line 1054 of file theme.cpp.

void Plasma::Theme::insertIntoCache	(	const QString &	key,
		const QPixmap &	pix,
		const 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

Definition at line 1061 of file theme.cpp.

void Plasma::Theme::insertIntoRectsCache	(	const QString &	image,
		const QString &	element,
		const 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

Definition at line 1132 of file theme.cpp.

void Plasma::Theme::invalidateRectsCache

(

const 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

Definition at line 1155 of file theme.cpp.

QStringList Plasma::Theme::listCachedRectKeys

(

const QString &

image

)

const

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

Definition at line 1109 of file theme.cpp.

KPluginInfo::List Plasma::Theme::listThemeInfo ( )

static

Returns

a list of all known themes

Since

4.3

Definition at line 599 of file theme.cpp.

PackageStructure::Ptr Plasma::Theme::packageStructure ( )

static

Returns

a package structure representing a Theme

Definition at line 590 of file theme.cpp.

void Plasma::Theme::releaseRectsCache

(

const 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

Definition at line 1165 of file theme.cpp.

void Plasma::Theme::setCacheLimit

(

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.

Definition at line 1178 of file theme.cpp.

void Plasma::Theme::setFont	(	const QFont &	font,
		FontRole	role = 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

Definition at line 964 of file theme.cpp.

void Plasma::Theme::setThemeName

(

const QString &

themeName

)

Sets the current theme being used.

Definition at line 627 of file theme.cpp.

void Plasma::Theme::settingsChanged ( )

slot

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

Definition at line 619 of file theme.cpp.

void Plasma::Theme::setUseGlobalSettings

(

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

Definition at line 1003 of file theme.cpp.

QString Plasma::Theme::styleSheet

(

const QString &

css = QString()

)

const

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

Definition at line 836 of file theme.cpp.

void Plasma::Theme::themeChanged ( )

signal

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.

QString Plasma::Theme::themeName

(

)

const

Returns

the name of the theme.

int Plasma::Theme::toolTipDelay

(

)

const

Returns

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

Definition at line 1196 of file theme.cpp.

bool Plasma::Theme::useGlobalSettings

(

)

const

Returns

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

Definition at line 1015 of file theme.cpp.

bool Plasma::Theme::useNativeWidgetStyle

(

)

const

Returns

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

Definition at line 1020 of file theme.cpp.

QString Plasma::Theme::wallpaperPath

(

const QSize &

size = QSize()

)

const

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

Definition at line 852 of file theme.cpp.

bool Plasma::Theme::windowTranslucencyEnabled

(

)

const

Returns

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

Definition at line 998 of file theme.cpp.

Property Documentation

QString Plasma::Theme::themeName

read

Definition at line 59 of file theme.h.

---

The documentation for this class was generated from the following files:

• theme.h
• theme.cpp